Event Notifications
This document serves as a guide for merchants intending to consume event notifications. It provides instructions on subscribing to events, understanding the limitations of the notification service, and links to further information on the available destinations/events.
How it works
The notification service has the following properties:
Eventually Consistent: Events within our system maintain an eventual consistency model, ensuring that data updates eventually propagate across the network.
At Least Once Delivery: Guaranteed sending of events to subscribers, ensuring merchants receive event notifications at least once. An endpoint may receive the same event more than once, and should de-duplicate by checking the event ID.
Non-Retry: Events do not undergo a retry process - once sent, it will not retry if the downstream service is not available. In the event of merchant downtime, reconciliation can be performed using data exports or Bento APIs.
Unordered: No guarantees are given for the ordering of events that will be sent, even within topics for the same resource. A created event may be sent after an updated event, for example. The emittedAt meta field can be used to order or disregard messages within your systems.
.webp "Z6kFt8taC1HaZhGGDq_Rb_bento-documentation-diagrams-event-notification-service(1).webp")
Event Format
All of our events contain the following fields:
Field Name | Description |
|---|---|
eventId | a unique identifier for the event |
version | used to identify the version of the internal schema for the body, when combined with eventType and eventAction |
eventType | the type of resource the event is for, e.g. customer, order or subscription |
eventAction | the action taken as part of the event, e.g. created, updated, committed |
emittedAt | the time the event was created within Bento, which may differ from the time it is being sent |
body | the unique payload for the eventType, eventAction and version combination. The Events documentation defines the payload for each of these resources. |
Example order-committed event
{
"eventId": "7fdf6a42-8948-11ee-b9d1-0242ac120002",
"version": 1,
"eventType": "order",
"eventAction": "committed",
"emittedAt": "2023-08-15T02:44:23.688Z",
"body": {...}
}Further Information
See our documentation on possible destinations for events:
See our documentation on the different events you can subscribe to: