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.
Intentos automáticos
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. |
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. |
Pending y se programa para envío inmediato.
Reglas para consumidores
- Procesa cada evento de forma idempotente.
- Guarda
eventId para deduplicar el evento de negocio.
- Guarda
attemptId si necesitas auditar cada entrega.
- No dependas del orden estricto entre eventos.
- Consulta la API si necesitas confirmar el estado final.
- Registra los datos originales para auditoría y depuración.
- Verifica
X-HMAC-Signature antes de confiar en los datos.
Patrón recomendado
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.
