commercelayer-webhooks

Commerce Layer Webhooks

When to Use This Skill

• How do I receive Commerce Layer webhooks?
• How do I verify Commerce Layer webhook signatures?
• How do I handle orders.place, orders.approve, or orders.pay events?
• Why is my Commerce Layer X-CommerceLayer-Signature verification failing?
• Setting up a Commerce Layer callback endpoint for order/shipment events

Verification (core)

Commerce Layer signs the raw request body with HMAC-SHA256 keyed on the webhook's shared_secret and sends the digest as base64 in the X-CommerceLayer-Signature header. The triggering topic is in X-CommerceLayer-Topic. The shared_secret is returned once, in the response when you create the webhook (POST /api/webhooks) — it is not the same as your API credentials.

Read the raw body, NOT the parsed one. Re-serializing parsed JSON changes bytes (key order, whitespace) and breaks the signature. Commerce Layer has no SDK verify helper, so verify manually (this matches the official docs example).

Node:

const crypto = require('crypto');

function verifyCommerceLayerSignature(rawBody, signature, sharedSecret) {
  if (!signature) return false;
  const expected = crypto
    .createHmac('sha256', sharedSecret)
    .update(rawBody) // rawBody is a Buffer/string — never JSON.parse first
    .digest('base64');
  try {
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  } catch {
    return false; // length mismatch = invalid
  }
}

Python:

import hmac, hashlib, base64

def verify_commercelayer_signature(raw_body: bytes, signature: str, shared_secret: str) -> bool:
    if not signature:
        return False
    expected = base64.b64encode(
        hmac.new(shared_secret.encode(), raw_body, hashlib.sha256).digest()
    ).decode()
    return hmac.compare_digest(signature, expected)

For complete handlers with route wiring, event dispatch, and tests, see:

• examples/express/
• examples/nextjs/
• examples/fastapi/