Seguridad de webhooks

Comprobar una entrega, rechazar una repetición, y por qué quien escucha debe hacer casi nada.

Un endpoint de webhook es una dirección de tu infraestructura a la que cualquiera en internet puede mandar un POST. La firma es lo que la convierte en algo que solo Nomi puede accionar.

1. 1

   Lee el cuerpo crudo

   Antes de interpretar ningún JSON. La firma cubre exactamente los bytes que se mandaron.

2. 2

   Vuelve a calcular el HMAC

   HMAC-SHA256 sobre ${t}.${rawBody} con el secreto del endpoint, comparado en tiempo constante.

3. 3

   Comprueba la frescura

   Rechaza una t de más de unos cinco minutos. La firma prueba el origen; la marca de tiempo prueba que no es una repetición.

4. 4

   Contesta rápido, trabaja después

   Acusa recibo con un 2xx y haz el trabajo real en una cola. Quien llama a tres servicios internos antes de contestar es quien se queda sin tiempo.

El código está en Webhooks, y comprueba exactamente lo que la plataforma firma.

Aguanta duplicados

Las entregas se reintentan, así que tu servicio va a ver el mismo evento dos veces tarde o temprano. Usa el identificador del evento como llave y haz idempotente el manejador: sale más barato que conseguir una entrega exactamente-una-vez, que no consigue nadie.

Si el secreto se filtra

Se rota. Lo hace quien administra la organización desde la consola, el secreto nuevo se muestra una sola vez, y desde ese momento las entregas van firmadas con él — así uno que acabó en una bitácora, una captura o un repositorio deja de poder falsificar nada.