técnico · respuesta con fuentes
Verificación de la firma del webhook
La verificación de la firma del webhook es un proceso de seguridad en el que el receptor valida una firma criptográfica adjunta a una solicitud HTTP entrante. Así se garantiza que el payload lo envió el proveedor de confianza y que no se alteró en tránsito.
Definición
La verificación de la firma del webhook es un mecanismo para autenticar el origen de un evento de webhook. Cuando un proveedor como Resend o SendGrid envía una notificación sobre un evento de correo, incluye un hash del payload firmado con una clave secreta. El servidor receptor usa la misma clave secreta para volver a calcular el hash y compararlo con la firma incluida en el encabezado de la solicitud.
Proceso técnico
El proveedor genera un hash HMAC a partir de un secreto compartido y del cuerpo de la solicitud. Este hash se envía en un encabezado, a menudo llamado X-Signature o similar. El receptor captura el cuerpo sin procesar de la solicitud y el encabezado de la firma. A continuación, calcula su propio hash HMAC con el secreto compartido. Si el hash calculado coincide con el valor del encabezado, la solicitud es auténtica. Si no coinciden, la solicitud se rechaza por no estar autorizada.
Por qué importa a los remitentes
Sin verificación, cualquiera que conozca la URL de su webhook puede enviar datos falsos a su servidor. Esto podría provocar actualizaciones incorrectas en la base de datos, como marcar como rebotado un correo entregado. Implementar la verificación evita los ataques de suplantación y garantiza que su aplicación solo reaccione a eventos legítimos generados por su infraestructura de correo.
Notas operativas
Un error común es convertir el cuerpo de la solicitud en un objeto JSON antes de verificar la firma. Como los analizadores de JSON pueden cambiar los espacios en blanco o el orden de las claves, la cadena resultante puede no coincidir con el payload original que usó el proveedor. Use siempre el cuerpo de la solicitud sin procesar ni analizar para los cálculos HMAC y así evitar fallos de verificación.
Ejemplo de implementación
En un entorno Node.js, un desarrollador usaría el módulo crypto para crear un hash hmac sha256 del cuerpo sin procesar con el secreto del proveedor. Después, compararía el resultado con el encabezado de la firma mediante una función de comparación en tiempo constante para evitar los ataques de temporización. SendHQ ofrece herramientas gratuitas en https://sendhq.cc/tools para ayudarle a gestionar distintas configuraciones de correo que suelen preceder a la configuración de los webhooks.
Preguntas habituales de los equipos
¿Qué ocurre si se filtra la clave secreta?
Si la clave secreta se ve comprometida, un atacante puede firmar solicitudes falsas que su servidor aceptará como válidas. Debe rotar la clave secreta de inmediato en el panel de su proveedor y actualizar las variables de entorno de su servidor.
¿HTTPS hace innecesaria la verificación de la firma?
No. HTTPS cifra los datos en tránsito y verifica la identidad del servidor, pero no verifica que el cliente concreto que envía la solicitud sea su proveedor de correo autorizado.
¿Por qué usar HMAC en lugar de una simple clave de API?
Las firmas HMAC demuestran que el contenido del mensaje no se ha manipulado. Una clave de API estática en un encabezado solo demuestra que el remitente conoce la clave, no que el payload esté intacto.
Fuentes primarias
- Documentación de Resend — Resend
- Documentación para desarrolladores de Postmark — Postmark
- Documentación de SendGrid — Twilio SendGrid