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 payout transactions | processing → success or failed |
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 | Unique webhook event identifier. |
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). |
provider | string | Processor that handled the transaction. |
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",
"provider": "tonder",
"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"
}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.
- Secure your endpoint to verify requests come from Tonder.
- Register your endpoint — see Set up webhooks.
- Process the notifications in your application.
A single URL is enough. You do not register one endpoint per payment method or per operation type. The URL you configure receives every method and operation — card, SPEI, OXXO, withdrawals.
The routing is on your side. Each notification carries the fields that let you identify what it
is, primarily event_type, operation_type and payment_method_type (or transfer_method_type
on withdrawals).
Endpoint requirements: use HTTPS (not HTTP), respond within 30 seconds, return a 2xx code to
acknowledge receipt, and authenticate requests to verify they come from Tonder (see
Set up webhooks for the BEARER, API_TOKEN, and BASIC_AUTH methods).
Common use cases
Reliability and delivery
| Mechanism | Detail |
|---|---|
| Delivery | Each event is delivered once. |
| Response timeout | 30 seconds. |
| Success criteria | Any 2xx HTTP code within the timeout. |
| Recovery | Reconcile via GET /api/v1/transactions/{id}/. |
Full details in Delivery.