How Webhooks Work
How Tonder delivers webhooks, what the payload contains, and why you confirm server-side.
Webhooks are automated messages Tonder sends when transaction events occur. Instead of repeatedly polling the API for status changes, webhooks notify you in real time the moment something happens — a payment completing, failing, or requiring additional authentication.
Key events
| Event type | Description | Example flow |
|---|---|---|
| Payment status changes | Real-time updates as the payment progresses | pending → authorized → success |
| Payment failures | When a payment is declined or fails | pending → declined or failed |
| 3DS authentication | When the user completes the 3D Secure challenge | pending_3ds → success or failed |
| Cash payment confirmations | When the customer pays an OXXO voucher | pending → success (when paid at store) |
| Withdrawal updates | Status changes for payouts | Pending → Success, Declined or Failed; a paid transfer whose funds come back adds Returned |
Payload structure (API Direct)
API Direct webhooks use a flat payload — all fields are at the top level, with no data wrapper.
Key fields:
| Field | Type | Description |
|---|---|---|
id | string | The transaction id. It repeats on every event of the same payment or withdrawal, so it does not identify one event: dedupe on the webhook-id header (Webhooks 2.0) or on id + event_type. |
operation_type | string | Operation type (e.g. payment). |
amount | string | Transaction amount (as a string). |
currency | string | ISO 4217 code (e.g. MXN). |
client_reference | string | Your transaction reference. |
status | string | Current status (Success, Pending, Failed). |
transaction_id | string | Tonder's internal identifier. |
payment_method_type | string | Method used (SPEI, CARD, OXXO). |
created | string | ISO 8601 timestamp. |
metadata | object | Key-value pairs sent when creating the payment. |
event_type | string | Event that triggered the notification (payment_Success, payment_Pending). |
action | string | Action associated with the event (e.g. MODIFY). |
{
"id": "fc38522e-3e5d-45b8-ba6a-ece72caee71f",
"operation_type": "payment",
"amount": "70",
"currency": "MXN",
"client_reference": "ORD-001",
"status": "Success",
"transaction_id": "e9340a04-6d68-4afc-86c5-79f8b7c87de4",
"payment_method_type": "SPEI",
"created": "2026-05-21T19:15:32.029134Z",
"metadata": {
"order_id": "ORD-001",
"external_id": "ORD-001",
"transaction_type": "deposit"
},
"event_type": "payment_Success",
"action": "MODIFY"
}Payloads can also carry fields that identify the institution that processed the transaction.
Don't build logic on them: use event_type and status.
Two webhook formats exist — Short (API Direct, Lite SDK 2.0, Hosted Checkout 2.0) and Long (mobile SDKs, legacy) — depending on your integration mode. See the Webhooks model.
Getting started with webhooks
- Create a public HTTPS URL that receives POST requests.
- Create the endpoint in the dashboard and choose its events — see Endpoints.
- Verify that each webhook comes from Tonder — see Verify signatures.
- Process the notifications in your application.
Endpoints and event selection
With Webhooks 2.0 you can register up to 10 endpoints, and each one receives only the events
you select for it — for example, one endpoint for payments and another for withdrawals. Every
notification still carries the fields that identify what it is, primarily event_type,
operation_type and payment_method_type (or transfer_method_type on withdrawals), so a single
endpoint can also take everything and route on your side.
Webhooks 2.0 is enabled per account. If Developers in your dashboard has no Events tab, your account is on the previous version: ask your Tonder contact to enable it.
Without Webhooks 2.0, the one URL you configure receives every method and operation, with no selection by event.
Endpoint requirements: use HTTPS (not HTTP), answer with a 2xx code within 10 seconds (30 seconds
without Webhooks 2.0), and check that each request comes from Tonder — with the
signature and, if you want, an
authentication header.
Common use cases
Reliability and delivery
| Mechanism | Webhooks 2.0 | Without Webhooks 2.0 |
|---|---|---|
| Delivery | Retried automatically, up to 6 attempts over about 8.5 hours. | Each event is delivered once. |
| Response timeout | 10 seconds. | 30 seconds. |
| Success criteria | Any 2xx HTTP code within the timeout. | Any 2xx HTTP code within the timeout. |
| Authenticity | Every webhook is signed (Standard Webhooks). | The authentication header you configure. |
| Recovery | Resend from the Events log, or reconcile via GET /api/v1/transactions/{id}/. | Reconcile via GET /api/v1/transactions/{id}/. |
| History | 60 days in Developers › Events. | — |
Full details in Delivery and retries.