Firmar las peticiones
Cómo firmar lo que tu sistema envía a la API de casos y cómo verificar los avisos que Elion ITSM envía, con el formato Standard Webhooks.
En esta página
Todo lo que viaja entre tu sistema y la API de casos va firmado, en las dos direcciones, con el formato abierto Standard Webhooks. Así Elion ITSM sabe que la petición viene de tu sistema, y tu sistema sabe que el aviso viene de Elion ITSM.
La firma se calcula con un secreto. Úsalo solo en tu servidor: nunca en el navegador, en una app móvil ni en un repositorio de código.
Las cabeceras
Cabecera | Valor |
|---|---|
| Un identificador único por petición, por ejemplo un UUID. |
| La hora en segundos Unix. Se acepta con hasta 5 minutos de diferencia. |
|
|
Cómo se calcula la firma
Toma el secreto (
whsec_…), quita el prefijowhsec_y decodifica el resto desde base64: esa es la llave.Arma el texto
<webhook-id>.<webhook-timestamp>.<cuerpo>, donde el cuerpo son los bytes exactos que envías. En las consultasGETel cuerpo va vacío.Calcula HMAC-SHA256 de ese texto con la llave y codifícalo en base64.
Envía
webhook-signature: v1,<resultado>.
import crypto from 'node:crypto';
export function signedHeaders(secret: string, body: string): Record<string, string> {
const id = crypto.randomUUID();
const ts = Math.floor(Date.now() / 1000);
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const sig = crypto.createHmac('sha256', key).update(`${id}.${ts}.${body}`).digest('base64');
return { 'content-type': 'application/json', 'webhook-id': id, 'webhook-timestamp': String(ts), 'webhook-signature': `v1,${sig}` };
}Firma el mismo texto que envías. Si conviertes el objeto a JSON para firmarlo y luego otra librería lo vuelve a convertir al enviarlo, la firma no calza.
Verificar los avisos de Elion ITSM
Con el secreto de salida haces lo mismo al revés:
Lee el cuerpo crudo del aviso, antes de convertirlo a JSON.
Revisa que
webhook-timestampesté dentro de 5 minutos.Calcula la firma con el secreto de salida y compárala, en tiempo constante, con cada valor
v1,…dewebhook-signature. Durante una rotación vienen dos firmas separadas por un espacio: basta con que calce una.Guarda el
webhook-id. Si llega uno que ya procesaste, responde 200 sin repetir lo que hiciste.
Respuestas de Elion ITSM a una firma mala
Código | Motivo |
|---|---|
401 | Firma inválida, faltan cabeceras o la hora tiene más de 5 minutos de diferencia (revisa el reloj de tu servidor). |
404 | La URL del canal no existe, fue rotada o el canal está pausado. |
409 | Ese |