Verificar firmas
Tu endpoint de webhooks es una URL pública: cualquiera podría enviarle unPOST fingiendo ser Alara. Por eso cada entrega va firmada con el secreto de tu suscripción.
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.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
Conserva el cuerpo crudo
Conserva el cuerpo crudo
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.Compara en tiempo constante
Compara en tiempo constante
Usa
timingSafeEqual, hmac.compare_digest, hash_equals o hmac.Equal según tu lenguaje. Comparar cadenas con == filtra información sobre la firma correcta.Guarda el secreto de forma segura
Guarda el secreto de forma segura
Trátalo como cualquier otra credencial: variables de entorno o gestor de secretos, nunca en el repositorio.
Responde 2xx incluso si ignoras el evento
Responde 2xx incluso si ignoras el evento
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.
