DocumentaciónAjuda

Assinar as requisições

Como assinar o que seu sistema envia à API de casos e como verificar os avisos que o Elion ITSM envia, no formato Standard Webhooks.

Nesta página

Tudo o que trafega entre seu sistema e a API de casos vai assinado, nas duas direções, no formato aberto Standard Webhooks. Assim o Elion ITSM sabe que a requisição vem do seu sistema, e seu sistema sabe que o aviso vem do Elion ITSM.

A assinatura é calculada com um segredo. Use-o só no seu servidor: nunca no navegador, em um app móvel nem em um repositório de código.

Os cabeçalhos

Cabeçalho

Valor

webhook-id

Um identificador único por requisição, por exemplo um UUID.

webhook-timestamp

A hora em segundos Unix. É aceita com até 5 minutos de diferença.

webhook-signature

v1, seguido da assinatura em base64.

Como a assinatura é calculada

  1. Pegue o segredo (whsec_…), tire o prefixo whsec_ e decodifique o resto de base64: essa é a chave.

  2. Monte o texto <webhook-id>.<webhook-timestamp>.<cuerpo>, onde o corpo são os bytes exatos que você envia. Nas consultas GET o corpo vai vazio.

  3. Calcule o HMAC-SHA256 desse texto com a chave e codifique-o em base64.

  4. Envie 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}` };
}

Assine o mesmo texto que você envia. Se você converte o objeto em JSON para assiná-lo e depois outra biblioteca o converte de novo ao enviar, a assinatura não confere.

Verificar os avisos do Elion ITSM

Com o segredo de saída você faz o mesmo ao contrário:

  1. Leia o corpo bruto do aviso, antes de convertê-lo em JSON.

  2. Verifique se webhook-timestamp está dentro de 5 minutos.

  3. Calcule a assinatura com o segredo de saída e compare-a, em tempo constante, com cada valor v1,… de webhook-signature. Durante uma rotação vêm duas assinaturas separadas por um espaço: basta que uma confira.

  4. Guarde o webhook-id. Se chegar um que você já processou, responda 200 sem repetir o que fez.

Respostas do Elion ITSM a uma assinatura inválida

Código

Motivo

401

Assinatura inválida, faltam cabeçalhos ou a hora tem mais de 5 minutos de diferença (verifique o relógio do seu servidor).

404

A URL do canal não existe, foi rotacionada ou o canal está pausado.

409

Esse webhook-id já foi recebido. Nada foi feito.

Relacionado

Pesquisar em Elion ITSM

Digite pelo menos 2 letras para pesquisar em Elion ITSM.

↑↓ navegar · Enter abrir · Esc fechar