Reintentos y errores

Un webhook cruza dos sistemas. Debes asumir que puede haber reintentos, entregas duplicadas, caídas temporales o respuestas tardías.

Respuestas esperadas

Respuesta del receptor	Resultado recomendado
`2xx`	Evento aceptado. Bold puede marcar la entrega como correcta.
`4xx`	Error del consumidor o datos no aceptados. Revisa configuración y contrato.
`5xx`	Error temporal del receptor. El evento debe poder reintentarse.
Tiempo de espera agotado	El receptor no respondió a tiempo. Procesa con cola y responde rápido.

No devuelvas 2xx si descartaste el evento sin guardarlo. Bold asumirá que la entrega fue correcta.

Bold intenta enviar una notificación hasta cinco veces. Después de cada fallo, programa el siguiente intento con espera exponencial.

Dato	Comportamiento
Tiempo máximo de envío	30 segundos.
Intentos máximos	5 intentos automáticos.
Espera automática	`10 * 2^n` segundos, donde `n` es el número de intentos realizados.
Estado final tras agotar intentos	`Failure`.
Reintento manual	Solo para notificaciones en `Failure`, mediante `POST /v1/notifications/webhook/{id}/retry`.

Cada intento guarda código HTTP, cuerpo de respuesta o mensaje de error. Consulta GET /v1/notifications/webhook/{id}/attempts para diagnosticarlo.

Intento fallido	Siguiente intento aproximado
1	20 segundos después.
2	40 segundos después.
3	80 segundos después.
4	160 segundos después.
5	No hay siguiente intento automático.

Cuando solicitas un reintento manual, la notificación vuelve a Pending y se programa para envío inmediato.

Valida los datos enviados

Comprueba que eventName, majorVersion, minorVersion y el identificador de entidad son los esperados.

Detecta duplicados

Si ya procesaste el evento, devuelve 2xx y no repitas efectos externos.

Encola el trabajo

Guarda el evento en tu sistema y responde rápido.

Procesa en segundo plano

Ejecuta llamadas a sistemas de gestión, herramientas de análisis u otros servicios fuera del tiempo de respuesta HTTP.

if already_processed(event.eventId):
  return 200

store(event)
enqueue(event.eventId)
return 202

Si tu integración queda desincronizada, usa la API paginada para reconciliar el estado y después reactiva el procesamiento normal de webhooks.