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 |
|---|---|
| Un identifiant unique par requête, par exemple un UUID. |
| L'heure en secondes Unix. Un écart de 5 minutes maximum est accepté. |
|
|
Comment calculer la signature
Prenez le secret (
whsec_…), retirez le préfixewhsec_et décodez le reste depuis le base64 : c'est la clé.Construisez le texte
<webhook-id>.<webhook-timestamp>.<cuerpo>, où le corps correspond aux octets exacts que vous envoyez. Pour les requêtesGET, le corps est vide.Calculez le HMAC-SHA256 de ce texte avec la clé et encodez-le en base64.
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 :
Lisez le corps brut de la notification, avant de le convertir en JSON.
Vérifiez que
webhook-timestampse situe dans les 5 minutes.Calculez la signature avec le secret de sortie et comparez-la, en temps constant, avec chaque valeur
v1,…dewebhook-signature. Pendant un renouvellement, deux signatures arrivent séparées par une espace : il suffit que l'une corresponde.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 |