Webhooks entrantes: firma y marca de tiempo

El esquema más extendido es un código de autenticación de mensajes (HMAC) con un secreto que comparten el proveedor y el receptor. El proveedor calcula el código sobre el aviso y lo manda en una cabecera; el receptor lo recalcula con el mismo secreto y compara. Si coinciden, quien envió conoce el secreto y el contenido no cambió por el camino.

Eso es todo lo que prueba. No dice cuándo se envió ni si ya se recibió antes: un aviso legítimo copiado de un registro sigue teniendo una firma perfecta dentro de tres días. Por eso los proveedores serios incluyen en lo firmado una marca de tiempo y piden al receptor que rechace lo que se aleje demasiado de su reloj. CWE nombra las dos fallas por separado: verificar mal una firma criptográfica (CWE-347) y aceptar una autenticación capturada y repetida (CWE-294).

Abre el laboratorio. Lee webhook-pagos.js de arriba abajo antes de mirar el registro: el primer bloque decide qué pasa cuando falta la cabecera de firma, y el comentario explica por qué se escribió así. Luego compara con lo que dice documentacion-proveedor.txt sobre los avisos de prueba.

Un aviso falso procesado no es un problema de código: es un trasteo que se entrega sin cobrar. Cruza el registro con liquidacion-proveedor.txt. El proveedor solo liquida lo que de verdad cobró.

El código separa la marca de tiempo de la cabecera, la usa para calcular la firma y no vuelve a mirarla. Hay en el registro un aviso con firma válida que ya se había recibido, ahora desde una dirección fuera del rango que publica el proveedor. Mide cuánto tiempo pasó entre el momento firmado y su llegada, y compáralo con la tolerancia que recomienda el proveedor.

La nota al pie del registro cuenta el fallo opuesto: un aviso real se rechazó y el proveedor sí lo liquidó. Mira sobre qué texto calcula el receptor la firma y compáralo con lo que firma el proveedor según su documentación. Ese mismo detalle es el que empujó al equipo, semanas antes, a relajar otras comprobaciones.

Lo que hay que cambiar

El receptor correcto lee el cuerpo crudo, rechaza todo aviso sin cabecera de firma (los de prueba también vienen firmados, con su propio secreto), descarta la marca de tiempo que se aleje de la tolerancia acordada, calcula la firma sobre la marca y el cuerpo exactos y compara con una función de tiempo constante. La lista de direcciones del proveedor puede sumarse como capa adicional, pero no sustituye a la firma.