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 |
|---|---|
| Um identificador único por requisição, por exemplo um UUID. |
| A hora em segundos Unix. É aceita com até 5 minutos de diferença. |
|
|
Como a assinatura é calculada
Pegue o segredo (
whsec_…), tire o prefixowhsec_e decodifique o resto de base64: essa é a chave.Monte o texto
<webhook-id>.<webhook-timestamp>.<cuerpo>, onde o corpo são os bytes exatos que você envia. Nas consultasGETo corpo vai vazio.Calcule o HMAC-SHA256 desse texto com a chave e codifique-o em base64.
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:
Leia o corpo bruto do aviso, antes de convertê-lo em JSON.
Verifique se
webhook-timestampestá dentro de 5 minutos.Calcule a assinatura com o segredo de saída e compare-a, em tempo constante, com cada valor
v1,…dewebhook-signature. Durante uma rotação vêm duas assinaturas separadas por um espaço: basta que uma confira.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 |