API de webhooks
Administra endpoints y entregas por código —las mismas operaciones de Desarrolladores › Webhooks y Eventos, con tu llave de API.
Todo lo que haces en Desarrolladores › Webhooks y Desarrolladores › Eventos también está disponible por API, con la misma autenticación que el resto de la API de Tonder.
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.
URL base. Tu contacto de Tonder te da la URL base de cada ambiente (sandbox y producción). Las rutas de esta página son relativas a ella.
Autenticación
Authorization: Token YOUR_API_KEY
Content-Type: application/jsonGuarda esta llave en tu servidor. Con tu llave de API cualquiera puede agregar un endpoint y recibir tus eventos, rotar un secreto de firma o desactivar un endpoint. Nunca la pongas en código del frontend o de una app móvil. Si aparece en la lista un endpoint que no reconoces, elimínalo y rota la llave.
Operaciones
| Método y ruta | Para qué sirve |
|---|---|
GET /v1/endpoints | Lista tus endpoints. |
POST /v1/endpoints | Crea un endpoint (máximo 10). |
GET /v1/endpoints/{id} | Consulta un endpoint. |
PATCH /v1/endpoints/{id} | Edita un endpoint, incluido desactivarlo. |
DELETE /v1/endpoints/{id} | Elimina un endpoint. |
POST /v1/endpoints/{id}/rotate-secret | Genera un secreto de firma nuevo. |
POST /v1/endpoints/{id}/test | Envía un evento endpoint.test. |
GET /v1/event-types | El catálogo de eventos y la política de reintentos. |
GET /v1/deliveries | Lista las entregas. |
GET /v1/deliveries/stats | Cuenta las entregas por estado. |
GET /v1/deliveries/{id} | Consulta una entrega con todos sus intentos. |
POST /v1/deliveries/{id}/retry | Reenvía una entrega. |
POST /v1/deliveries/retry | Reintenta las entregas Fallidas que coinciden con un filtro. |
Lista las entregas
GET /v1/deliveries acepta estos parámetros de consulta:
| Parámetro | Descripción |
|---|---|
status | Estado de la entrega. |
event_type | Tipo de evento. Repite el parámetro para incluir varios. |
endpoint_id | Un endpoint. |
from, to | Rango de fechas en ISO 8601. Por defecto los últimos 7 días; máximo 60. |
search | La misma búsqueda del registro de eventos: id de la transacción, client_reference o metadata.external_id, id de transacción de Tonder, evt_… o dlv_…. |
limit | Tamaño de página, hasta 100. 25 por defecto. |
cursor | El next_cursor de la página anterior. |
Cuando hay más resultados, la respuesta trae next_cursor: pásalo como cursor, con los mismos
filtros, para obtener la siguiente página.
Límites
300 lecturas y 60 escrituras por minuto por comercio, compartidas con el dashboard. Al pasarlos
recibes un 429 con header Retry-After.
Errores
Todo error responde con un objeto error:
| Campo | Descripción |
|---|---|
error.code | Código para máquinas. |
error.message | Explicación legible. |
error.details | Contexto adicional del error. |
error.code | Significado |
|---|---|
url_not_allowed | La URL del endpoint no empieza con https:// o apunta a una dirección privada o interna. |
retry_in_progress | Ya hay un intento en curso para esa entrega. |
endpoint_unavailable | El endpoint está desactivado o eliminado. |
Siguientes pasos
Registro de eventos
Cada webhook que Tonder envió a tus endpoints, con cada intento y la respuesta de tu servidor — busca, filtra y reenvía desde Desarrolladores › Eventos.
Buenas prácticas y deduplicación
Cómo hacer tu endpoint de webhooks seguro, idempotente y rápido, más las respuestas a las preguntas más frecuentes de los comercios.