DocumentaciónAide

Signer les requêtes

Comment signer ce que votre système envoie à l'API de dossiers et comment vérifier les notifications qu'envoie Elion ITSM, au format Standard Webhooks.

Sur cette page

Tout ce qui circule entre votre système et l'API de dossiers est signé, dans les deux sens, au format ouvert Standard Webhooks. Ainsi, Elion ITSM sait que la requête vient de votre système, et votre système sait que la notification vient d'Elion ITSM.

La signature se calcule avec un secret. Utilisez-le uniquement sur votre serveur : jamais dans le navigateur, dans une application mobile ni dans un dépôt de code.

Les en-têtes

En-tête

Valeur

webhook-id

Un identifiant unique par requête, par exemple un UUID.

webhook-timestamp

L'heure en secondes Unix. Un écart de 5 minutes maximum est accepté.

webhook-signature

v1, suivi de la signature en base64.

Comment calculer la signature

  1. Prenez le secret (whsec_…), retirez le préfixe whsec_ et décodez le reste depuis le base64 : c'est la clé.

  2. Construisez le texte <webhook-id>.<webhook-timestamp>.<cuerpo>, où le corps correspond aux octets exacts que vous envoyez. Pour les requêtes GET, le corps est vide.

  3. Calculez le HMAC-SHA256 de ce texte avec la clé et encodez-le en base64.

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

Signez exactement le texte que vous envoyez. Si vous convertissez l'objet en JSON pour le signer et qu'une autre bibliothèque le reconvertit à l'envoi, la signature ne correspond pas.

Vérifier les notifications d'Elion ITSM

Avec le secret de sortie, vous faites la même chose en sens inverse :

  1. Lisez le corps brut de la notification, avant de le convertir en JSON.

  2. Vérifiez que webhook-timestamp se situe dans les 5 minutes.

  3. Calculez la signature avec le secret de sortie et comparez-la, en temps constant, avec chaque valeur v1,… de webhook-signature. Pendant un renouvellement, deux signatures arrivent séparées par une espace : il suffit que l'une corresponde.

  4. Conservez le webhook-id. S'il en arrive un que vous avez déjà traité, répondez 200 sans refaire ce que vous avez fait.

Réponses d'Elion ITSM à une mauvaise signature

Code

Motif

401

Signature non valide, en-têtes manquants ou heure décalée de plus de 5 minutes (vérifiez l'horloge de votre serveur).

404

L'URL du canal n'existe pas, a été renouvelée ou le canal est en pause.

409

Ce webhook-id a déjà été reçu. Rien n'a été fait.

Voir aussi

Rechercher dans Elion ITSM

Saisissez au moins 2 caractères pour rechercher dans Elion ITSM.

↑↓ naviguer · Enter ouvrir · Esc fermer