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 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.
{
"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 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.
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). 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.
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.validationonly 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:
{
"id": "9f8d3c2b-1a4e-4f6d-8b0c-2e5a7d9f1c34",
"object": "user.validation",
"createdAt": "2026-07-22T09:15:00Z",
"test": false,
"credentials": { "type": "recipientId", "recipientId": "player-42931" }
}
idis new for every check. Use it to match your logs with ours, not as an idempotency key.testistruewhen the check was sent to your Test URL. Check the ID against your test players then.credentials.typeisrecipientId, the only type today.credentials.recipientIdis 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.
Your answer
Answer with HTTP 200 and whether the player exists:
{ "valid": true }
{ "valid": false }
- Return
200whether the player exists or not. Tokenz reads a status outside 2xx (a redirect too) or a body withoutvalidas 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
validand, 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:
{ "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
idas 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 400s).
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 POSTs.
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).5xxor 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. - 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
testflag. - 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
2xxfirst, then process asynchronously.
4. Confirm delivery independently. Point your endpoint (or a copy of it) at 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).