Skip to main content

Webhooks

Webhooks notify your system when something relevant happens in Onebox: a purchase, a refund, a ticket transfer, an access validation, a change in an event or a session… Instead of polling the APIs, you expose an HTTPS endpoint and Onebox sends it an HTTP POST request every time one of the events you subscribed to occurs.

How webhooks work​

Webhooks are notifications, not data feeds. The body tells you what changed (an order code, an event id) and the headers tell you how it changed; to get the current state, call the API. Order notifications include the URL of the order to fetch.

This model keeps payloads small and always gives you fresh data, even if notifications arrive late or out of order.

Anatomy of a request​

POST /your-webhook HTTP/1.1
Content-Type: application/json; charset=utf-8
ob-event: ORDER
ob-action: PURCHASE
ob-delivery-id: 5b9f3c1a-7e2d-4a16-9c40-1b3a4d57e802
ob-hook-id: c244aa20-afa7-4734-8b95-67d37b66ac04
ob-signature: a7757d032af8276fc88a940b33db42f107f1d51e91d216b365c953cda185cdc3

{
  "code" : "9N1FTEJKTQH2",
  "url" : "https://api.oneboxtds.com/orders-mgmt-api/v1/orders/9N1FTEJKTQH2"
}

Headers​

HeaderDescription
ob-eventThe type of object that changed: ORDER, ITEM, EVENT_UPDATE… See the event reference.
ob-actionWhat happened to it: PURCHASE, REFUND, TRANSFER… Each event has its own set of actions.
ob-subtypeOptional. Finer detail for some events, such as which part of an event or a session changed.
ob-hook-idIdentifier of the webhook configuration that sent the request. Use it to pick the API key that verifies the signature.
ob-signatureSHA-256 signature of the body. See Verify signatures.
ob-delivery-idIdentifier of the delivery, for logging and support.

Body​

A JSON object whose fields depend on ob-event. Order notifications carry the order code and its url; catalog notifications carry numeric identifiers of the event, session or channel that changed. The event reference documents every payload.

Verify the signature on the raw body, exactly as received, before you parse it.

Configure a webhook​

Webhooks are managed through the Management API, in its Webhooks section, and your operator can also manage them from the Control Panel. For each webhook you choose:

  • The URL that receives the requests. Use the final address of your endpoint: redirects are not supported.
  • The events and actions you want to receive, such as ORDER_PURCHASE or EVENT_CATALOG.
  • The scope: ENTITY receives the notifications of your whole entity; CHANNEL receives the order notifications of a single sales channel.

Each webhook has its own API key, which signs every request it sends. You can have several webhooks, for example one per system that consumes them.

The quickstart walks you through creating a webhook and receiving your first request.

Next steps​