Usage Guide

How to integrate with VLMS events

Consuming Events

VLMS publishes events whenever significant actions occur in the system. The preferred method for consuming these events is to provide an HTTP endpoint that receives webhook deliveries.

To set up webhook delivery, provide your endpoint URL to the Magnus team. Events will be POSTed to your endpoint as they occur.

Subscription Confirmation

When your endpoint is first registered, it will receive a subscription confirmation request. Your endpoint must handle this confirmation by visiting the SubscribeURL provided in the request body to activate the subscription.

Event Filtering

Subscriptions can be limited to a specific subset of events. If you only need certain event types, contact the Magnus team to configure filtering for your endpoint. Unwanted events can be excluded from delivery upon request.

Event Ordering

There is no guarantee that events will be delivered in order. The queue is not FIFO, so events may arrive out of sequence. Use the EventTimestamp field to determine the actual order of operations when processing events.

Tip

Your endpoint should return a 2xx status code to acknowledge receipt. Failed deliveries will be retried.

Event Structure

All events are wrapped in a standard envelope containing:

  • Id - Unique event identifier
  • EventTimestamp - When the event occurred (UTC)
  • EventSource - Contains event name, domain, and system
  • EventObj - The event-specific payload
  • InstanceKey - Environment identifier

See the Reference page for detailed payload structures by domain.

Best Practices

Idempotency

Events may be delivered more than once. Use the Id field from the envelope to deduplicate and ensure each event is processed only once.

Error Handling

Implement robust error handling to avoid message loss:

  • Only delete messages after successful processing
  • Use a dead-letter queue for repeatedly failing messages
  • Log failed events for manual review

Filtering

Process only the events you need by checking EventSource.Domain and EventSource.Name fields to route events to the appropriate handlers.

Warning

Don't assume event ordering. Events may arrive out of sequence. Use EventTimestamp to determine the actual order of operations.