Modelo de webhooks
Los dos formatos de webhook de Tonder, qué integración recibe cada uno y cómo leerlos.
Los webhooks son mensajes automáticos que Tonder envía cuando ocurren eventos de una transacción. En lugar de consultar la API una y otra vez por cambios de estado, los webhooks te notifican en tiempo real en el momento en que algo sucede —un pago que se completa, falla o requiere autenticación adicional.
Dos formatos: Short y Long
Tonder envía dos formatos de webhook distintos. El que recibes depende de tu modo de integración:
- API Direct, Lite SDK 2.0 y Hosted Checkout 2.0 → formato Short
- SDKs móviles / Legacy (incluidas las cuentas de Hosted Checkout que siguen en el flujo legacy) → formato Long
| Característica | Formato Short | Formato Long |
|---|---|---|
| Estructura raíz | Campos de nivel superior | Todo dentro de data{} |
| Campo de estado | status: Pending / Success | transaction_status: Pending / Success |
| Indicador de evento | event_type: payment_Pending | event: created / confirmed |
| Referencia de orden | client_reference | metadata.external_id / order_id |
| CLABE de SPEI | No incluida | data.clabe |
| Info del remitente (SPEI Success) | No incluida | sender_name, sender_clabe, sender_bank… |
_incoming_request | No incluido | metadata._incoming_request (objeto completo) |
| Modos de integración | API Direct · Lite SDK 2.0 · Frictionless SPEI · Hosted Checkout 2.0 | SDKs móviles · Legacy |
La misma transacción, dos estructuras
El siguiente ejemplo es un evento de SPEI en ambos formatos:
{
"id": "78eb98ef-65a8-4038-a2a0",
"operation_type": "payment",
"amount": "500",
"currency": "MXN",
"client_reference": "ORD-001",
"status": "Pending",
"provider": "tonder",
"transaction_id": "26292298-de5e-4edc",
"payment_method_type": "SPEI",
"created": "2026-05-21T19:51:18Z",
"metadata": {
"order_id": "ORD-001",
"external_id": "ORD-001",
"transaction_type": "deposit"
},
"event_type": "payment_Pending",
"action": "MODIFY"
}{
"operation_type": "payment",
"action": "payment",
"event": "created",
"type": "deposit",
"data": {
"id": "3195511b-fd2e-4844-bf02",
"transaction_status": "Pending",
"amount": 500.0,
"currency_code": "MXN",
"payment_id": 5117665,
"payment_method_name": "spei",
"clabe": "710969000312511566",
"concept": "SPEI deposit for payment...",
"metadata": {
"external_id": "ORD-001",
"order_id": "ORD-001",
"transaction_type": "deposit"
}
}
}Es la misma transacción con dos estructuras completamente distintas. Confirma tu formato con tu gerente de integración de Tonder antes de construir tu handler de webhooks.
Retiros
Los webhooks de retiros tienen dos formatos propios, y cuál recibes depende de cómo esté
configurado tu comercio. El formato plano tiene la
misma forma que el formato Short de pagos (status: Pending, event_type: withdrawal_Pending,
transfer_method_type en lugar de payment_method_type). El formato extendido anida el
registro completo del retiro bajo withdrawal{} y lleva el estado en los nombres internos
(PAID_FULL). Los dos están documentados, con ejemplos, en
Retiros.
Clave de correlación
Los nombres de los campos de referencia difieren entre modos, pero metadata.external_id llega
en todos los formatos y eventos. Úsalo como tu clave de correlación.
| Modo | Campo en la petición (envías) | Campo en el webhook (lees) |
|---|---|---|
| Hosted Checkout | external_id | metadata.external_id |
| SDK (cualquier plataforma) | orderReference | metadata.external_id o metadata.order_id |
| API Direct | client_reference | client_reference (nivel raíz) + metadata.external_id |
| Híbrido | ambos, por leg | ambos formatos — correlaciona por metadata.external_id |
Regla universal: incluye metadata.external_id en cada petición — es el único campo
garantizado en todos los webhooks de todos los formatos.