Receive Tokenz events in your webhook endpoint

Listen to events in your Tokenz account on your webhook endpoint so your integration can automatically trigger reactions.

Why use webhooks

When building Tokenz Checkout integrations, your applications should receive events as they occur in your Tokenz account so that your backend systems can execute actions accordingly.

To enable webhook events, you need to register webhook endpoints. After registering them, Tokenz can push real-time event data to your application's webhook endpoint when events happen in your Tokenz account. Tokenz uses HTTPS to send webhook events to your app as a JSON payload with an Event object.

We strongly recommend implementing webhooks in addition to handling redirects from our checkout to ensure that you always receive notification of the checkout result.

Event object

When an event occurs, Tokenz generates a new Event object. A single API request might create multiple events.

By registering webhook endpoints in your Tokenz account, you enable Tokenz to automatically send Event objects as part of POST requests to the registered webhook endpoint hosted by your application. After your webhook endpoint receives the Event, your app can run backend actions (for example, sending the customer a download link for their purchased item or topping up their account balance after you receive an order.succeeded event).

The Event object we send to your webhook endpoint provides a snapshot of the changed object. The webhook always contains the full object on which the event occurred, along with event metadata.

Example event payload

The following example shows an Event sent for a successful order.

{
  "id": "event_...",
  "object": "event",
  "createdAt": "2024-06-20T04:37:02.495Z",
  "signature": "...",
  "eventData": {
    "type": "order.succeeded",
    "version": "1.0.0",
    "data": order
  }
}

Live and test mode

You might receive event delivery requests for both live and test mode to your endpoints if you use a single endpoint for both live and test mode. Use the test flag to check whether the object exists in live or test mode and determine the correct handling for the event.

Version

The version indicates the API version of the event and dictates the structure of the included data.object.

Types of events