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 retiros | Pending → Success, Declined o Failed; una transferencia pagada cuyos fondos vuelven agrega Returned |
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 | El id de la transacción. Se repite en cada evento del mismo pago o retiro, así que no identifica un evento: deduplica con el header webhook-id (Webhooks 2.0) o con id + event_type. |
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). |
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",
"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"
}El payload también puede traer campos que identifican a la institución que procesó la transacción.
No construyas lógica sobre ellos: usa event_type y status.
Existen dos formatos de webhook —Short (API Direct, Lite SDK 2.0, Hosted Checkout 2.0) y Long (SDKs móviles, legacy)— 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.
- Crea el endpoint en el dashboard y elige sus eventos —ver Endpoints.
- Verifica que cada webhook viene de Tonder —ver Verifica la firma.
- Procesa las notificaciones en tu aplicación.
Endpoints y selección de eventos
Con Webhooks 2.0 puedes registrar hasta 10 endpoints, y cada uno recibe solo los eventos que
elijas para él —por ejemplo, un endpoint para pagos y otro para retiros. Cada notificación sigue
trayendo los campos que identifican qué es, principalmente event_type, operation_type y
payment_method_type (o transfer_method_type en retiros), así que un solo endpoint también puede
recibirlo todo y enrutar de tu lado.
Webhooks 2.0 se habilita por cuenta. Si en Desarrolladores de tu dashboard no aparece la pestaña Eventos, tu cuenta está en la versión anterior: pide a tu contacto de Tonder que la habilite.
Sin Webhooks 2.0, la única URL que configuras recibe todos los métodos y operaciones, sin selección por evento.
Requisitos del endpoint: usar HTTPS (no HTTP), responder con un código 2xx en menos de 10 segundos
(30 segundos sin Webhooks 2.0) y comprobar que cada petición viene de Tonder —con la
firma y, si quieres, un
header de autenticación.
Casos de uso comunes
Fiabilidad y entrega
| Mecanismo | Webhooks 2.0 | Sin Webhooks 2.0 |
|---|---|---|
| Entrega | Se reintenta automáticamente, hasta 6 intentos en unas 8,5 horas. | Cada evento se entrega una sola vez. |
| Timeout de respuesta | 10 segundos. | 30 segundos. |
| Criterio de éxito | Cualquier código HTTP 2xx dentro del timeout. | Cualquier código HTTP 2xx dentro del timeout. |
| Autenticidad | Cada webhook viene firmado (Standard Webhooks). | El header de autenticación que configures. |
| Recuperación | Reenvía desde el registro de eventos, o concilia con GET /api/v1/transactions/{id}/. | Concilia con GET /api/v1/transactions/{id}/. |
| Historial | 60 días en Desarrolladores › Eventos. | — |
Detalles completos en Entrega y reintentos.
Siguientes pasos
Cash vouchers en Colombia (COP)
Efectivo en Efecty, SuRed, MovilRed y Acciones y Valores, o transferencia en línea desde 44 bancos y billeteras, en pesos colombianos, con los IDs de banco de cada red.
Endpoints
Crea endpoints de webhook, elige los eventos que recibe cada uno y adminístralos desde el dashboard.