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 y Lite SDK 2.0 → formato Short
- Hosted Checkout / SDKs móviles / 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 · 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.
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 — deduplica 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.