Verifying signatures

Documentation Index

Fetch the complete documentation index at: https://docs.exowizz.com/llms.txt

Use this file to discover all available pages before exploring further.

​

How signing works

1. Serializes the JSON payload
2. Computes an HMAC-SHA256 hash using the subscription’s secret as the key
3. Sends the hash in the X-Exo-Signature header, prefixed with sha256=

​

Verifying in your receiver

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_EXO_SIGNATURE'] ?? '';
$secret = 'your-webhook-secret';

$expected = 'sha256=' . bin2hex(
    hash_hmac('sha256', $payload, $secret, binary: true)
);

if (! hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$data = json_decode($payload, true);
// Process the webhook...

const crypto = require('crypto');

app.post('/webhook-receiver', (req, res) => {
  const payload = JSON.stringify(req.body);
  const signature = req.headers['x-exo-signature'] || '';
  const secret = 'your-webhook-secret';

  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  if (signature !== expected) {
    return res.status(401).send('Invalid signature');
  }

  // Process the webhook...
  res.status(200).send('OK');
});

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

​

Important notes

• Always use a constant-time comparison function (like hash_equals in PHP or hmac.compare_digest in Python) to prevent timing attacks.
• The signature is computed on the raw JSON body of the request, not on any parsed or reformatted version. Make sure you read the raw body before parsing.
• Each webhook subscription has its own unique secret, generated when the subscription is created. If you have multiple subscriptions, use the correct secret for each one.

​

Webhook request format

{
  "event": "on_create",
  "resource": "order",
  "event_id": "01JT1M2X3B2W3PW8ZAF2X36JMY",
  "delivery_id": "01JT1M2Y9HF38TEHSEK5EN9V5C",
  "data": {
    "id": 42,
    "order_number": "ORD-001",
    "status": "pending"
  },
  "timestamp": "2026-03-28T14:30:00.123456Z"
}

​

Handling failures