Saltar al contenido principal

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:

  1. 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á.
  2. Compara en tiempo constante, con la función que tu lenguaje tenga para ello, no con un ==.
  3. Compara las longitudes antes. La función de tiempo constante de casi todos los lenguajes —timingSafeEqual en 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.
  4. 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:

CabeceraQué lleva
X-Webhook-EventCuál de los diez avisos es
X-Webhook-SignatureEl HMAC-SHA256 del cuerpo, en hexadecimal y sin prefijo
X-Webhook-DeliveryEl identificador del envío, el mismo en los reintentos
X-Webhook-AttemptPor 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.


¿Esto no te resuelve la duda?

Si ya usas GuauKit, abre un aviso desde Soporte, en la propia aplicación: nos llega con tu centro y tu plan, y te contestamos allí mismo. Si todavía no tienes cuenta, escríbenos.