Sign requests
How to sign what your system sends to the case API and how to verify the notifications Elion ITSM sends, with the Standard Webhooks format.
On this page
Everything that travels between your system and the case API is signed, in both directions, with the open Standard Webhooks format. That way Elion ITSM knows the request comes from your system, and your system knows the notification comes from Elion ITSM.
The signature is calculated with a secret. Use it only on your server: never in the browser, in a mobile app or in a code repository.
The headers
Header | Value |
|---|---|
| A unique identifier per request, for example a UUID. |
| The time in Unix seconds. It is accepted with up to 5 minutes of difference. |
|
|
How the signature is calculated
Take the secret (
whsec_…), remove thewhsec_prefix and decode the rest from base64: that is the key.Build the text
<webhook-id>.<webhook-timestamp>.<body>, where the body is the exact bytes you send. InGETrequests the body is empty.Calculate the HMAC-SHA256 of that text with the key and encode it in base64.
Send
webhook-signature: v1,<result>.
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}` };
}Sign the same text you send. If you convert the object to JSON to sign it and then another library converts it again when sending it, the signature will not match.
Verify Elion ITSM notifications
With the outbound secret you do the same in reverse:
Read the notification's raw body, before converting it to JSON.
Check that
webhook-timestampis within 5 minutes.Calculate the signature with the outbound secret and compare it, in constant time, with each
v1,…value inwebhook-signature. During a rotation, two signatures come separated by a space: it is enough for one to match.Store the
webhook-id. If one arrives that you already processed, answer 200 without repeating what you did.
Elion ITSM responses to a bad signature
Code | Reason |
|---|---|
401 | Invalid signature, missing headers or the time differs by more than 5 minutes (check your server's clock). |
404 | The channel URL does not exist, was rotated or the channel is paused. |
409 | That |