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 recordtime/emittedAt meta field can be used to order or disregard messages within your systems.

Event Format

Events sent from Bento Box are evolving from a custom legacy format to an industry-standard CloudEvent format. These formats are defined below, and each event type will indicate which format it uses.

CloudEvent Format

Field Name	Type	Example	Description
specversion	String	“1.0”	The version of CloudEvents specification being used
type	String	"com.bento.order.event.billing-attempted"	The identifier for the event
source	String	"com.bento.service.billing"	The service that produced the event
subject	String	“487281d7-471c-4fb2-a6b6-9f670add8004”	The id of the entity that the event relates to
id	String	“01JTJMY39RXYX61BFFGS5HX91W123”	A unique identifier for the event
time	Datetime	"2025-06-04T08:15:28.933Z"	The time that the event occurred, if it can be determined; otherwise the time of event publication.
recordtime	Datetime	25-06-04T08:15:28.933Z"	Represents the time that the event was fired. This is different from time to allow for services to order event processing in different ways.
datacontenttype	String	"application/json"	The format of the data within the data field, where possible this should be application/json to aid interoperability between services
deprecated	Boolean	false	Information about deprecation status of the event
deprecationfrom	Optional Datetime	"2025-06-04T12:00:00.000933Z"	When the event was deprecated from
deprecationsunset	Optional String	"2025-06-04T12:00:00.000933Z"	When the deprecated event will be sunset
deprecationmigration	Optional String	“Migration steps xyz“	Information on how to migrate from a deprecated event
data	Ref datacontenttype	See Events

Legacy Custom Format

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:
- Destinations
See our documentation on the different events you can subscribe to:
- Events