La API y las integraciones a medida
Verificar la firma de un webhook
Actualizado el 5 de octubre de 2026
Cada llamada va firmada con HMAC-SHA256 usando tu secreto, sobre el cuerpo exacto del mensaje. Tu servidor debe comprobar esa firma antes de fiarse de nada: sin esa comprobación, cualquiera que descubra tu dirección puede inventarse un aviso de «factura pagada».
La firma llega en la cabecera X-Webhook-Signature, en hexadecimal pelado: sin sha256= ni ningún otro prefijo delante.
Cuatro reglas al implementarlo:
- Calcula el HMAC sobre el cuerpo crudo que recibes, tal cual llega. Si lo conviertes a objeto y lo vuelves a serializar, cambian el orden y los espacios, y ninguna firma coincidirá.
- Compara en tiempo constante, con la función que tu lenguaje tenga para ello, no con un
==. - Compara las longitudes antes. La función de tiempo constante de casi todos los lenguajes —
timingSafeEqualen Node, por ejemplo— lanza una excepción si los dos valores miden distinto. Sin esa comprobación previa, una firma mal formada te tumba el receptor con un 500 en vez de rechazarse. - Si falta la firma o no coincide, responde 403 y no proceses nada. Nunca «si no viene firma, lo doy por bueno».
El cuerpo llega con esta forma, y solo con estas tres claves —la entidad no viaja dentro: cada webhook es de una y solo una—:
{
"event": "invoice.paid",
"timestamp": "2026-07-30T10:15:00.000Z",
"data": { }
}
Y estas son las cuatro cabeceras de cada envío:
| Cabecera | Qué lleva |
|---|---|
X-Webhook-Event | Cuál de los diez avisos es |
X-Webhook-Signature | El HMAC-SHA256 del cuerpo, en hexadecimal y sin prefijo |
X-Webhook-Delivery | El identificador del envío, el mismo en los reintentos |
X-Webhook-Attempt | Por qué intento va (1 es el primero) |
En /api-docs hay un ejemplo de verificación listo para copiar, con la comprobación de longitudes ya puesta.