Cómo funcionan los webhooks
Cómo entrega Tonder los webhooks, qué contiene el payload y por qué debes confirmar del lado del servidor.
Los webhooks son mensajes automáticos que Tonder envía cuando ocurren eventos de una transacción. En lugar de consultar la API repetidamente 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.
Eventos clave
| Tipo de evento | Descripción | Ejemplo de flujo |
|---|---|---|
| Cambios de estado del pago | Actualizaciones en tiempo real conforme avanza el pago | pending → authorized → success |
| Fallas de pago | Cuando un pago es rechazado o falla | pending → declined o failed |
| Autenticación 3DS | Cuando el usuario completa el reto 3D Secure | pending_3ds → success o failed |
| Confirmación de pago en efectivo | Cuando el cliente paga un voucher OXXO | pending → success (al pagar en tienda) |
| Actualizaciones de retiro | Cambios de estado de los pagos salientes | processing → success o failed |
Estructura del payload (API Direct)
Los webhooks de API Direct usan un payload plano —todos los campos están en el nivel superior, sin
un envoltorio data. Campos clave:
| Campo | Tipo | Descripción |
|---|---|---|
id | string | Identificador único del evento de webhook. |
operation_type | string | Tipo de operación (p. ej. payment). |
amount | string | Monto de la transacción (como string). |
currency | string | Código ISO 4217 (p. ej. MXN). |
client_reference | string | Tu referencia de la transacción. |
status | string | Estado actual (Success, Pending, Failed). |
provider | string | Procesador que manejó la transacción. |
transaction_id | string | Identificador interno de Tonder. |
payment_method_type | string | Método usado (SPEI, CARD, OXXO). |
created | string | Marca de tiempo ISO 8601. |
metadata | object | Pares clave-valor enviados al crear el pago. |
event_type | string | Evento que disparó la notificación (payment_Success, payment_Pending). |
action | string | Acción asociada al evento (p. ej. 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"
}Existen dos formatos de webhook —Short (API Direct, Lite SDK 2.0) y Long (Hosted Checkout, SDKs móviles)— según tu modo de integración. Consulta el Modelo de webhooks.
Empezar con webhooks
- Crea una URL HTTPS pública que reciba peticiones POST.
- Asegura tu endpoint para verificar que las peticiones vienen de Tonder.
- Registra tu endpoint —ver Configurar webhooks.
- Procesa las notificaciones en tu aplicación.
Requisitos del endpoint: usar HTTPS (no HTTP), responder en menos de 30 segundos, devolver un código
2xx para confirmar la recepción y autenticar las peticiones para verificar que vienen de Tonder
(ver Configurar webhooks para los métodos BEARER, API_TOKEN y
BASIC_AUTH).
Casos de uso comunes
Fiabilidad y entrega
| Mecanismo | Detalle |
|---|---|
| Reintentos automáticos | Hasta 3 intentos de entrega, con intervalos de 60 segundos. |
| Timeout de respuesta | 30 segundos por intento. |
| Dead Letter Queue | Los eventos fallidos se guardan 30 días para reprocesamiento manual. |
| Criterio de éxito | Cualquier código HTTP 2xx dentro del timeout. |
Detalles completos en Entrega y reintentos.