Verifying Webhook Signatures - Mage Loyalty Documentation

Every webhook request includes an X-Webhook-Signature header containing an HMAC-SHA256 signature. You must verify this signature before processing the payload — otherwise anyone who discovers your endpoint URL could send fake events.

How it works

Mage Loyalty signs every webhook using your subscription’s signing secret:

A signing string is created by concatenating the timestamp, a dot, and the raw request body: {timestamp}.{rawBody}
The signing string is hashed with HMAC-SHA256 using your signing secret as the key
The result is hex-encoded and prefixed with sha256=

Your server repeats the same process and compares the result.

Step-by-step

Extract the headers

Read X-Webhook-Signature and X-Webhook-Timestamp from the incoming request.

X-Webhook-Signature: sha256=a1b2c3d4e5f6...
X-Webhook-Timestamp: 2026-02-18T12:00:00.000Z

Get the raw request body

You need the raw body string exactly as it was received — not a parsed-and-re-serialized version. Most frameworks provide a way to access this.

If you parse the JSON body and then JSON.stringify() it, the output may differ from the original (different key ordering, whitespace). This will cause signature verification to fail. Always use the raw body.

Build the signing string

Concatenate the timestamp, a literal . character, and the raw body:

2026-02-18T12:00:00.000Z.{"event":"points.earned","shop":"my-store",...}

Compute the expected signature

Create an HMAC-SHA256 hash of the signing string using your signing secret, then hex-encode it and prepend sha256=.

Compare using a timing-safe function

Compare your computed signature with the X-Webhook-Signature header using a timing-safe comparison function. Do not use === or == — these are vulnerable to timing attacks.If the two values match, the webhook is verified.

Complete examples

Node.js
Python
Ruby
PHP

const crypto = require('crypto');

function verifyWebhook(req, secret) {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];
  const rawBody   = req.body; // raw request body string — NOT parsed JSON

  // 1. Build the signing string
  const signingString = timestamp + '.' + rawBody;

  // 2. Compute the expected signature
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(signingString)
    .digest('hex');

  // 3. Timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Express example — make sure to capture the raw body:

const express = require('express');
const app = express();

// Capture the raw body as a string alongside the parsed JSON
app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf.toString('utf8');
  }
}));

app.post('/webhooks/loyalty', (req, res) => {
  const isValid = verifyWebhook(
    { headers: req.headers, body: req.rawBody },
    process.env.MAGE_WEBHOOK_SECRET
  );

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

  const { event, data } = req.body;
  console.log(`Received ${event}`, data);

  res.status(200).send('OK');
});

import hmac
import hashlib

def verify_webhook(signature: str, timestamp: str, raw_body: str, secret: str) -> bool:
    # 1. Build the signing string
    signing_string = f"{timestamp}.{raw_body}"

    # 2. Compute the expected signature
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"),
        signing_string.encode("utf-8"),
        hashlib.sha256
    ).hexdigest()

    # 3. Timing-safe comparison
    return hmac.compare_digest(signature, expected)

Flask example:

from flask import Flask, request, abort

app = Flask(__name__)

@app.route("/webhooks/loyalty", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-Webhook-Signature", "")
    timestamp = request.headers.get("X-Webhook-Timestamp", "")
    raw_body = request.get_data(as_text=True)

    if not verify_webhook(signature, timestamp, raw_body, MAGE_WEBHOOK_SECRET):
        abort(401)

    payload = request.get_json()
    print(f"Received {payload['event']}", payload["data"])
    return "OK", 200

require 'openssl'

def verify_webhook(signature, timestamp, raw_body, secret)
  # 1. Build the signing string
  signing_string = "#{timestamp}.#{raw_body}"

  # 2. Compute the expected signature
  digest = OpenSSL::HMAC.hexdigest('sha256', secret, signing_string)
  expected = "sha256=#{digest}"

  # 3. Timing-safe comparison
  ActiveSupport::SecurityUtils.secure_compare(signature, expected)
end

function verifyWebhook(
  string $signature,
  string $timestamp,
  string $rawBody,
  string $secret
): bool {
    // 1. Build the signing string
    $signingString = $timestamp . '.' . $rawBody;

    // 2. Compute the expected signature
    $expected = 'sha256=' . hash_hmac('sha256', $signingString, $secret);

    // 3. Timing-safe comparison
    return hash_equals($expected, $signature);
}

Replay attack protection (optional)

The X-Webhook-Timestamp header is included in the signed data, so it cannot be forged. You can optionally reject requests where the timestamp is too old:

const MAX_AGE_MS = 5 * 60 * 1000; // 5 minutes

function isTimestampValid(timestamp) {
  const age = Date.now() - new Date(timestamp).getTime();
  return age >= 0 && age <= MAX_AGE_MS;
}

Troubleshooting

Signature mismatch — common causes

Re-serialized body: You parsed the JSON and re-stringified it. Use the raw body exactly as received.
Wrong secret: Each webhook subscription has its own unique signing secret. Make sure you’re using the correct one.
Middleware modified the body: Some frameworks (e.g. Express without the verify option) consume the raw body during JSON parsing. Use the verify callback shown above to preserve it.
Encoding issues: The raw body must be read as UTF-8. Binary or other encodings will produce a different hash.

I lost my signing secret

Signing secrets are shown only once at creation time. If you’ve lost yours, go to Settings > Webhooks, edit the subscription, and click Rotate signing secret. A new secret will be generated and shown once. Update your server with the new secret — the old one is immediately invalidated.

How do I test locally?

Use a tunneling tool like ngrok to expose your local server, then register the tunnel URL as your webhook endpoint. You can also use the Test button in the dashboard to send a test event.

Documentation Index

​How it works

​Step-by-step

​Complete examples

​Replay attack protection (optional)

​Troubleshooting

How it works

Step-by-step

Complete examples

Replay attack protection (optional)

Troubleshooting