DocumentaciónAyuda

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

webhook-id

Un identificador único por petición, por ejemplo un UUID.

webhook-timestamp

La hora en segundos Unix. Se acepta con hasta 5 minutos de diferencia.

webhook-signature

v1, seguido de la firma en base64.

Cómo se calcula la firma

  1. Toma el secreto (whsec_…), quita el prefijo whsec_ y decodifica el resto desde base64: esa es la llave.

  2. Arma el texto <webhook-id>.<webhook-timestamp>.<cuerpo>, donde el cuerpo son los bytes exactos que envías. En las consultas GET el cuerpo va vacío.

  3. Calcula HMAC-SHA256 de ese texto con la llave y codifícalo en base64.

  4. 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:

  1. Lee el cuerpo crudo del aviso, antes de convertirlo a JSON.

  2. Revisa que webhook-timestamp esté dentro de 5 minutos.

  3. Calcula la firma con el secreto de salida y compárala, en tiempo constante, con cada valor v1,… de webhook-signature. Durante una rotación vienen dos firmas separadas por un espacio: basta con que calce una.

  4. 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 webhook-id ya se recibió. No se hizo nada.

Relacionado

Buscar en Elion ITSM

Escribe al menos 2 letras para buscar en Elion ITSM.

↑↓ moverse · Enter abrir · Esc cerrar