--- title: "Receive Tokenz events in your webhook endpoint" description: "Listen to events in your Tokenz account on your webhook endpoint so your integration can automatically trigger reactions." source: "https://docs.tokenz.one/en/v3/checkout/webhooks" api_version: "v3" locale: "en" version_status: "current" docs_stage: "prod" --- # 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. **Amount format:** Monetary values in webhook payloads (such as `amount` fields) are expressed in the smallest minor unit of each currency. See [Supported currencies](https://docs.tokenz.one/en/v3/checkout/currency) for the exact encoding per currency. ## Why use webhooks When building Tokenz Checkout integrations, your applications should receive events as they occur in your 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. ```json { "id": "a1b2c3d4-e5f6-7g8h-9i0j-k1l2m3n4o5p6", "object": "order.succeeded", "createdAt": "2025-09-24T03:22:20.297Z", "test": true, "eventData": { "type": "order", "version": "v3", "data": { "order": { "id": "order_1D5xA9BnKfv_t", "object": "order", "status": "succeeded", "amount": { "amount": 3700, "currency": "JPY" }, "items": [ { "id": "item_1D6F8mR5TnK_t", "detail": { "product": { "price": { "amount": 1200, "currency": "JPY" }, "quantity": 3, "label": "ひとにぎりのエメラルド", "description": "80+8", "images": [ "https://images.ctfassets.net/z82qbo7cv7ia/1dWPbk5Qx2M1Qikj6Knyuc/e37b2c26829c0d30793a348ae3adb3b0/fake-pass.webp" ] } } }, { "id": "item_1xejV7puGeK_t", "detail": { "product": { "price": { "amount": 100, "currency": "JPY" }, "quantity": 1, "label": "Diamond", "description": "", "images": [], "sku": "sku_103843dfjhdfgiu", "taxCategory": "VIRTUAL_CURRENCY" } } } ], "description": "Game items purchase", "externalOrderId": "ORDER_2024_001", "recipientId": "user_42931", "metadata": { "cartId": "cart_8812" }, "test": true, "expiresAt": "2024-12-31T23:59:59Z", "createdAt": "2024-01-15T10:00:00Z", "updatedAt": "2024-01-15T10:05:30Z" } } } } ``` ### 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 and the shape of the entity in `eventData.data`, such as `eventData.data.order` in the example above. ### Types of events | TYPE | DESCRIPTION | | --- | --- | | `order.created` | A new order is created via the [Create a Checkout Session](https://docs.tokenz.one/en/v3/api/main) endpoint. | | `order.succeeded` | An order was successfully paid by your customer. You can deliver the items to the customer. | | `order.expired` | An order has expired. | | `order.canceled` | An order has been canceled. | | `order.failed` | An order payment has failed. | | `refund.created` | A refund has been created. | | `refund.failed` | A refund has failed. | | `dispute.created` | A dispute has been created. | | `dispute.closed` | A dispute has been closed. | | `redemption.completed` | A Gift Code has been redeemed or a Free Item has been claimed. The redemption `kind` identifies the flow (`source` is deprecated); `code` is omitted for Free Item claims. | `user.validation` is not in this list: it is a request that your endpoint answers, not an event. See [Recipient ID checks](https://docs.tokenz.one/en/v3/checkout/webhooks#player-id-checks). ## Recipient ID checks Your Tokenz webshop checks the recipient ID a player types, before they buy or claim a free item. For each check, Tokenz sends a `user.validation` request to ask your server whether an account with that recipient ID exists, unless it can reuse an earlier answer (see [Reused answers](https://docs.tokenz.one/en/v3/checkout/webhooks#player-id-check-reuse)). Tokenz reads your answer from the response, waits at most 3 seconds, and never retries it. Creating a Checkout Session doesn't send it, whether through the API or from the webshop. For the full request and response schema, see the [User validation API reference](https://docs.tokenz.one/en/v3/api/user-validation). ### Set the validation URL - Set the URL on **Settings** > **Developers** > **User validation**. Test and Live each have their own URL and signing secret, so switch the dashboard to the mode you want first. The signing secret is shown once, when it is generated. - Tokenz sends `user.validation` only to this URL. A webhook endpoint never receives it, even one that receives all events. - To check your server, enter a recipient ID from your game and select **Send test validation**. The dashboard shows your server's answer. Tokenz keeps nothing. - Your webshop can't be activated for Live until a Live validation URL is set. A purchase on your Live webshop is checked at your Live URL, with `test` set to `false`. A purchase in a Test preview is checked at your Test URL, with `test` set to `true`. If no Test URL is set, the Test preview accepts the typed ID without checking it. ### The request Tokenz sends a `POST` with a JSON body: ```json { "id": "9f8d3c2b-1a4e-4f6d-8b0c-2e5a7d9f1c34", "object": "user.validation", "createdAt": "2026-07-22T09:15:00Z", "test": false, "credentials": { "type": "recipientId", "recipientId": "player-42931" } } ``` - `id` is new for every check. Use it to match your logs with ours, not as an idempotency key. - `test` is `true` when the check was sent to your Test URL. Check the ID against your test players then. - `credentials.type` is `recipientId`, the only type today. `credentials.recipientId` is the recipient ID the player typed. The request carries the same `Tokenz-Signature` header as event deliveries, made with the signing secret of the validation URL, not a webhook endpoint's. Verify it over the raw request body before you answer. See [Secure your webhook endpoint](https://docs.tokenz.one/en/v3/checkout/webhooks-get-started#3.-secure-your-webhook-endpoint). ### Your answer Answer with HTTP `200` and whether the player exists: ```json { "valid": true } ``` ```json { "valid": false } ``` - Return `200` whether the player exists or not. Tokenz reads a status outside 2xx (a redirect too) or a body without `valid` as an outage, not as an unknown player. - Answer within 3 seconds. If Tokenz gets no verdict in time, the player can't pay and is asked to try again. Retries and idempotency below apply only to events. - Return `valid` and, optionally, `validUntil`, without player details. The player can learn whether the check passed; Tokenz does not forward your raw response to the player. ### Reused answers After a `true` answer from your Live URL, Tokenz may answer later checks for the same recipient ID within the same merchant project without calling you, for a few minutes by default. To choose how long, add `validUntil`, a date and time, to a `true` answer: ```json { "valid": true, "validUntil": "2026-07-22T09:45:00Z" } ``` A `false` answer is never reused, so a player who corrects their ID is checked again. Checks sent to your Test URL always reach your server. ## Retries and idempotency Tokenz expects your endpoint to acknowledge a webhook with a 2xx response. If your endpoint responds with any other status code, times out, or is unreachable, Tokenz automatically retries delivery for up to three days. The first retries are attempted approximately 5 seconds, 15 seconds, and 30 seconds after a failed delivery. Later retries use increasing delays and become less frequent over time. Retry timing may vary slightly; do not depend on an exact later-attempt schedule. Once your endpoint returns a 2xx response, Tokenz stops retrying that event. Your endpoint can receive the same event more than once, and events can arrive out of order. Handle deliveries idempotently: - Durably store the event before returning a 2xx response, then perform any heavy processing asynchronously. - Use the event's top-level `id` as an idempotency key: record the event ids you have processed and skip any event you have already handled, so a retried delivery cannot double-fulfill an order. ## Troubleshooting: my endpoint isn't receiving events Almost always, "the webhook never arrived" means Tokenz **did** send it and your endpoint **rejected** it. Tokenz treats any non-`2xx` response (or a timeout or unreachable endpoint) as a failed delivery and automatically retries for up to three days — so from your side it can look like nothing arrived, while Tokenz keeps seeing the same delivery fail (for example, a run of `HTTP 400`s). If event delivery history is available in your dashboard, open the event or endpoint to inspect delivery status, HTTP responses and attempts. Access depends on your role. If the history is unavailable, use your server's access and error logs to diagnose delivery. **1. Check the HTTP status your endpoint returned.** This is exactly what Tokenz sees — look in your server's access/error logs for the incoming `POST`s. - `2xx` — the event was delivered and acknowledged. If your system still didn't act on it, the problem is in your handler _after_ the response, not in delivery. - `400`, `401`, `403` — your endpoint received the event but rejected it (see below). - `5xx` or a timeout — your handler errored or was too slow to respond. **2. If you're returning `400`, check signature verification first** — it's the most common cause: - **Verify over the raw request body.** Most frameworks parse and re-serialize JSON, which changes the bytes and breaks the HMAC. Read the exact raw bytes (for example with `express.raw()`), verify, and only then parse. See [Secure your webhook endpoint](https://docs.tokenz.one/en/v3/checkout/webhooks-get-started#3.-secure-your-webhook-endpoint). - **Use the correct signing secret.** It is shown only once when you register the endpoint and is specific to that endpoint; a rotated or mistyped secret fails every event. - **Match test and live mode.** A test-mode event verified against your live signing secret (or the reverse) will never match. If one endpoint serves both, choose the secret using the event's `test` flag. - **Watch for clock skew.** If you reject on the 5-minute timestamp tolerance, a badly skewed server clock can reject otherwise-valid events. **3. Other causes of a non-2xx response:** - A firewall, WAF, or IP allowlist in front of your endpoint blocking Tokenz's request. - The endpoint is not publicly reachable over **HTTPS**, or the URL registered in the dashboard is wrong or points at the wrong environment. - Heavy work in the request path causing a timeout — acknowledge with a `2xx` first, then process asynchronously. **4. Confirm delivery independently.** Point your endpoint (or a copy of it) at [Webhook.site](https://webhook.site/) to confirm Tokenz is delivering and to inspect the exact payload and headers, then trigger an event with a test-mode payment. Once your endpoint returns `2xx`, retries stop. Because a retry can re-send an event you already processed, keep your handler idempotent (see above).