Webhooks en producción

La sección de webhooks cubre lo básico; esta es la lista de comprobación para producción.

El contrato

• La entrega es al menos una vez (at-least-once) y sin orden garantizado. Elimina duplicados por el id del evento y trata data.object como el estado actual más reciente, no como un diff.
• Responde 2xx rápido (encola y después procesa). El tiempo de espera es de 10 s.
• Reintentos: 1 min → 5 min → 30 min → 2 h → 12 h; después, la entrega se da por fallida.
• Tras 20 fallos consecutivos, el endpoint se desactiva automáticamente. Lo verás en Configuración → Desarrolladores → Webhooks (vuelve a activarlo después de arreglarlo).

Verifica cada entrega

Comprueba X-Nembol-Signature (t=…,v1=…, HMAC-SHA256 de <t>.<raw body> con el secreto de tu endpoint). El código completo está en Verificar firmas. Durante una rotación del secreto, se envían ambas firmas, la antigua y la nueva, durante 24 h.

Puntos a tener en cuenta

• Usa el cuerpo de la solicitud sin procesar para el HMAC. Cualquier reserialización rompe la firma.
• ¿Te perdiste una ventana? Las entregas fallidas se pueden reenviar desde el panel (Webhooks → entregas → Reenviar), y GET /events es tu forma de recuperarlas: los eventos se conservan 30 días.
• Los endpoints deben ser HTTPS en un host público: un nombre de dominio (ni una dirección IP, ni localhost, *.localhost, *.local o *.internal) que resuelva a una dirección pública. Un nombre que resuelve a una dirección privada o interna se rechaza en el momento de la entrega (el intento falla).
• Prueba primero: el botón Enviar evento de prueba del panel llama a tu endpoint con un evento ficticio firmado. Conecta la comprobación de la firma antes de pasar a producción.

Última actualización el 20 de octubre de 2026