Webhooks

Reintentos de webhooks

Lo que cuenta como entregado, lo que se reintenta, cuánto se espera y cuándo un webhook se da por muerto o se apaga solo.

Qué pasa con cada respuesta

Tu respuesta	Resultado	Reintentos
`2xx`	Entregado (succeeded). El contador de fallos del webhook vuelve a 0.	—
`429 · 5xx · 408`	Fallo transitorio. En `429` y `503` se respeta tu `Retry-After`.	Hasta 8 intentos.
Timeout (> 10 s) · error de red · TLS	Fallo transitorio.	Hasta 8 intentos.
`3xx`	No se sigue. Fallo permanente.	Hasta 3 intentos.
`4xx`	Fallo permanente (suele ser configuración: firma, ruta, auth).	Hasta 3 intentos.

Esperas

Tras cada fallo, la siguiente entrega espera 30 s · 2^{(intento − 1)}, con tope de 64 minutos:

Tras el intento	1	2	3	4	5	6	7
Espera	30 s	1 min	2 min	4 min	8 min	16 min	32 min

A cada espera se le suma un margen aleatorio de ±10 %: si tu servidor vuelve de una caída, las entregas acumuladas no llegan todas en el mismo segundo. Ocho intentos suman algo más de una hora (63,5 min de espera acumulada). El worker pasa cada minuto, así que cada espera real puede ser hasta un minuto mayor. Agotados los intentos, la entrega pasa a dead y ya no se reintenta.

`Retry-After`: si lo pides, se respeta

En un 429 o un 503, la cabecera Retry-After de tu respuesta manda sobre nuestra espera. Vale en segundos (Retry-After: 120) o como fecha HTTP. Se acota entre 1 segundo y 64 minutos; un valor que no se entienda se ignora y se usa la espera normal. En otros códigos no se tiene en cuenta.

Si el proceso de entrega se cae a mitad

Al empezar a entregarse, una entrega queda reservada con un plazo. Si el proceso muere antes de escribir el resultado (un despliegue, un tiempo de ejecución agotado), pasado el plazo la entrega vuelve sola a la cola y se reintenta. Ese intento cuenta como gastado, así que el número total de intentos no cambia y nada se queda parado para siempre.

Esto puede darte un duplicado

Si el proceso murió después de que tu servidor recibiera el POST, recibirás ese mismo evento otra vez: mismo X-WAT-Event-Id, mismo X-WAT-Delivery y mismo cuerpo, con otro X-WAT-Timestamp y otra firma. La entrega es «al menos una vez»: trata los eventos de forma idempotente y descarta los que ya hayas procesado guardando el X-WAT-Event-Id (o el id del cuerpo) al menos 24 horas.

Desactivación automática

Cada fallo suma 1 a consecutive_failures del webhook (entregas distintas incluidas); cada 2xx lo pone a 0. Al llegar a 100 fallos seguidos el webhook se desactiva (active: false, disabled_reason) y deja de recibir entregas nuevas. Para reactivarlo: PATCH /v1/webhooks/{id} con { "active": true }, que también pone el contador a 0.

Lo que no se reintenta

Una URL que ha dejado de resolver a una dirección pública, un secreto ilegible, una integración desactivada o un webhook que tú has puesto en active: false llevan la entrega directamente a dead con el motivo en last_error. Desactivar un webhook no aparca lo que estaba en cola: lo que caiga en ese rato se reconcilia luego con GET /events.

Recuperarse

Mira GET /v1/webhooks/{id}/deliveries: status, last_status, last_error y next_retry_at dicen qué pasa.
Si el webhook está desactivado, arregla el destino y reactívalo con PATCH.
Lo que quedó en dead no vuelve solo: reconcilia con GET /events y lee las reservas afectadas.

No hay endpoint para reenviar una entrega concreta en v1. Si necesitas un reenvío puntual, pídelo a soporte (info@wearetransfers.com) con el id de la entrega.