Call webhooks: verifying the signature

Last updated: 9 October 2026 · 4 min read

Steps

1. 1

   Headers

   • X-ChatX-Delivery: the delivery's id, the same as delivery_id in the body.
   • X-ChatX-Timestamp: when it was sent, in Unix seconds.
   • X-ChatX-Signature: sha256= followed by an HMAC-SHA256 signature.
2. 2

   How the signature is made

   The signature is computed over <timestamp>.<body> with the webhook's secret. Do not parse the JSON and serialise it again: verify the raw body as it arrived. Reject a request whose timestamp is older than 5 minutes. On a retry the timestamp and the signature are computed again; delivery_id stays the same.

3. 3

   Node.js

   const crypto = require('crypto');
   
   function verify(rawBody, headers, secret) {
     const timestamp = headers['x-chatx-timestamp'];
     const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
     const given = headers['x-chatx-signature'] || '';
     const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;
     return fresh && given.length === expected.length && crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
   }

4. 4

   Python

   import hashlib, hmac, time
   
   def verify(raw_body: bytes, headers, secret: str) -> bool:
       timestamp = headers["X-ChatX-Timestamp"]
       expected = "sha256=" + hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
       fresh = abs(time.time() - int(timestamp)) < 300
       return fresh and hmac.compare_digest(headers.get("X-ChatX-Signature", ""), expected)