Webhooks

Firma, verificación y deduplicación.

Cabeceras

X-Drivenbox-Event:      shipment.delivered
X-Drivenbox-Event-Id:   oev_01J...
X-Drivenbox-Timestamp:  1754400000
X-Drivenbox-Signature:  v1=<hex>

Verificación

HMAC-SHA256(timestamp + "." + cuerpo_crudo, signing_secret)

Debe verificar sobre el cuerpo crudo, byte a byte. Si su framework parsea el JSON y usted lo vuelve a serializar antes de verificar, la firma nunca coincidirá. Es el error más común al integrar webhooks firmados.

Obligatorio en su handler

Comparación en tiempo constante.
Rechazar timestamps fuera de ±300 s.
Deduplicar por X-Drivenbox-Event-Id: la entrega es at-least-once.
Responder 2xx rápido y procesar en segundo plano.

Reintentos

Backoff exponencial con jitter. Un 5xx o 429 se reintenta; un 4xx no, porque repetirá el mismo rechazo. Tras suficientes fallos seguidos el endpoint se desactiva y se lo informamos.

URLs permitidas

Sólo HTTPS hacia direcciones públicas. Se rechazan loopback, redes privadas, direcciones link-local y de metadatos de nube, URLs con credenciales embebidas y redirecciones. La comprobación se repite en cada entrega, no sólo al registrar.