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.
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 identifierEventTimestamp- When the event occurred (UTC)EventSource- Contains event name, domain, and systemEventObj- The event-specific payloadInstanceKey- 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.
Don't assume event ordering. Events may arrive out of sequence. Use EventTimestamp to determine the actual order of operations.