Skip to main content

Verificar firmas

Tu endpoint de webhooks es una URL pública: cualquiera podría enviarle un POST fingiendo ser Alara. Por eso cada entrega va firmada con el secreto de tu suscripción.
Verifica siempre la firma antes de procesar un evento. Sin esa comprobación, cualquiera podría inventar escaneos o saldos en tu sistema.

Encabezados de la entrega

Ejemplo:

Cómo se calcula la firma

1

Se arma la cadena a firmar

El timestamp en segundos Unix, un punto, y el cuerpo crudo de la petición:
2

Se calcula el HMAC

HMAC-SHA256 sobre esa cadena, usando como llave el secret de tu suscripción.
3

Se codifica en hexadecimal

El resultado, en hexadecimal minúsculas, es el valor de v1 dentro de Alara-Signature.
Debes firmar los bytes exactos que recibiste, no un JSON reserializado. Si tu framework parsea el cuerpo automáticamente, configúralo para conservar también el cuerpo crudo; de lo contrario un simple cambio de espacios hará que la firma nunca coincida.
El valor t= dentro de Alara-Signature siempre coincide con Alara-Webhook-Timestamp. Puedes usar cualquiera de los dos.

Ejemplos


Protección contra reenvíos

Alara no aplica una ventana de tolerancia del lado del servidor: esa validación te corresponde a ti.
1

Rechaza mensajes viejos

Descarta la entrega si Alara-Webhook-Timestamp se aleja del reloj de tu servidor más de lo razonable. Cinco minutos es un valor habitual.
2

Descarta duplicados

Guarda los Alara-Webhook-Id ya procesados y descarta los repetidos. La entrega es al menos una vez, así que los duplicados son normales, no un error.
El timestamp y la firma se recalculan en cada intento, así que un reintento llega con t y v1 distintos. Lo único estable entre intentos es Alara-Webhook-Id.

Lista de verificación

En Express, usa express.raw({ type: 'application/json' }) en la ruta del webhook. En otros frameworks, busca la opción equivalente antes de que el JSON se parsee.
Usa timingSafeEqual, hmac.compare_digest, hash_equals o hmac.Equal según tu lenguaje. Comparar cadenas con == filtra información sobre la firma correcta.
Trátalo como cualquier otra credencial: variables de entorno o gestor de secretos, nunca en el repositorio.
Si la firma es válida pero el evento no te interesa, responde 200 de todos modos. Un código de error hará que Alara lo reintente durante horas sin necesidad.Cuando la firma no es válida, responde 401 y no proceses nada.