DocumentaciónHelp

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

webhook-id

A unique identifier per request, for example a UUID.

webhook-timestamp

The time in Unix seconds. It is accepted with up to 5 minutes of difference.

webhook-signature

v1, followed by the signature in base64.

How the signature is calculated

  1. Take the secret (whsec_…), remove the whsec_ prefix and decode the rest from base64: that is the key.

  2. Build the text <webhook-id>.<webhook-timestamp>.<body>, where the body is the exact bytes you send. In GET requests the body is empty.

  3. Calculate the HMAC-SHA256 of that text with the key and encode it in base64.

  4. 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:

  1. Read the notification's raw body, before converting it to JSON.

  2. Check that webhook-timestamp is within 5 minutes.

  3. Calculate the signature with the outbound secret and compare it, in constant time, with each v1,… value in webhook-signature. During a rotation, two signatures come separated by a space: it is enough for one to match.

  4. 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 webhook-id was already received. Nothing was done.

Related

Search Elion ITSM

Type at least 2 characters to search Elion ITSM.

↑↓ to navigate · Enter to open · Esc to close