Verify BigCommerce webhooks

BigCommerce signs HTTPS webhooks under the Standard Webhooks spec, so you can confirm a delivery came from BigCommerce and wasn't changed or replayed. A Standard Webhooks library checks webhook-signature, an HMAC-SHA256 over webhook-id, webhook-timestamp and the raw body, using your client secret after you base64-encode it. BigCommerce's docs name the spec rather than the headers, and the body's hash field is an unkeyed SHA-1 for spotting duplicates, not a signature.

The facts

Signature header
webhook-signature

Format: v1,<base64> (space-separated when more than one)

Scheme
HMAC-SHA256, base64
Signed material
{webhook-id}.{webhook-timestamp}.{raw body}

The two headers and the body as sent, joined with full stops, per the Standard Webhooks spec that BigCommerce's docs delegate to.

Send timestamp
webhook-timestamp

Reject deliveries older than 5 minutes.

What to build
Verify with a Standard Webhooks library, passing the client secret base64-encoded
Key
shared secret

BigCommerce webhook secret

The signing key is your API account's client secret, base64-encoded before you hand it to a Standard Webhooks library. Keep it in an environment variable, not in source code.

  • Store-level API accounts are created in the control panel under **Settings > Store-level API accounts**. App-level accounts are created in the Developer Portal.
  • Base64-encode the client secret and pass the result to the library, which decodes it again. Passing the raw secret fails verification.
  • It isn't in Standard Webhooks' whsec_ format, and there's no per-webhook secret.
  • BigCommerce's docs say "client secret" without saying which account's. A webhook belongs to the API account that created it, so start with that one.
  • Rotation: BigCommerce says the client ID and client secret will never change. To replace a store-level account's credentials you delete the account, which also removes its webhooks.

Source: BigCommerce docs ↗

Code

express/src/index.js
javascript
// Generated with: bigcommerce-webhooks skill
// https://github.com/hookdeck/webhook-skills

require('dotenv').config();
const express = require('express');
const { Webhook, WebhookVerificationError } = require('standardwebhooks');

const app = express();

// BigCommerce signs callbacks using the Standard Webhooks spec.
// The signing key is your app's CLIENT SECRET, base64-encoded. The
// standardwebhooks library base64-decodes whatever you pass in, so encoding
// the client secret first yields the raw client-secret bytes as the HMAC key.
const clientSecret = process.env.BIGCOMMERCE_CLIENT_SECRET || '';
const wh = new Webhook(Buffer.from(clientSecret).toString('base64'));

// BigCommerce webhook endpoint - must use the raw body for signature verification.
app.post(
  '/webhooks/bigcommerce',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    let event;
    try {
      // verify() checks the HMAC-SHA256 signature over
      // `${webhook-id}.${webhook-timestamp}.${rawBody}`, enforces the
      // timestamp tolerance (replay protection), and returns the parsed JSON.
      event = wh.verify(req.body, {
        'webhook-id': req.headers['webhook-id'],
        'webhook-timestamp': req.headers['webhook-timestamp'],
        'webhook-signature': req.headers['webhook-signature'],
      });
    } catch (err) {
      if (err instanceof WebhookVerificationError) {
        console.error('BigCommerce webhook verification failed:', err.message);
        return res.status(400).send('Invalid signature');
      }
      console.error('Failed to process webhook:', err);
      return res.status(400).send('Invalid payload');
    }

    // BigCommerce payloads are thin: `scope` is the event, `data` carries only
    // the resource type and id. Call back to the REST API to fetch full details.
    const { scope, data } = event;

    switch (scope) {
      case 'store/order/created':
        console.log(`Order created: ${data?.id}`);
        // Your code: Fetch the order via GET /v2/orders/{id}, fulfil, notify
        break;

      case 'store/order/updated':
        console.log(`Order updated: ${data?.id}`);
        // Your code: Re-sync order details
        break;

      case 'store/order/statusUpdated':
        console.log(`Order status updated: ${data?.id}`);
        // Your code: Fetch order status, trigger fulfilment or refund flows
        break;

      case 'store/product/created':
        console.log(`Product created: ${data?.id}`);
        // Your code: Index the new product in your catalog
        break;

      case 'store/product/updated':
        console.log(`Product updated: ${data?.id}`);
        // Your code: Re-sync product details
        break;

      case 'store/product/deleted':
        console.log(`Product deleted: ${data?.id}`);
        // Your code: Remove the product from your catalog
        break;

      case 'store/product/inventory/updated':
        console.log(`Product inventory updated: ${data?.id}`);
        // Your code: Update stock levels downstream
        break;

      case 'store/customer/created':
        console.log(`Customer created: ${data?.id}`);
        // Your code: Sync customer to CRM / marketing list
        break;

      case 'store/cart/created':
        console.log(`Cart created: ${data?.id}`);
        // Your code: Track cart for analytics
        break;

      case 'store/cart/abandoned':
        console.log(`Cart abandoned: ${data?.id}`);
        // Your code: Trigger an abandoned-cart recovery email
        break;

      default:
        console.log(`Unhandled scope: ${scope}`);
    }

    // Respond 200 immediately so BigCommerce marks delivery successful.
    // Do heavy work asynchronously (queue) to avoid retries and blocklisting.
    res.status(200).json({ received: true });
  }
);

// Health check endpoint
app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

// Export app for testing
module.exports = app;

// Start server only when run directly (not when imported for testing)
if (require.main === module) {
  const PORT = process.env.PORT || 3000;
  app.listen(PORT, () => {
    console.log(`Server running on http://localhost:${PORT}`);
    console.log(`Webhook endpoint: POST http://localhost:${PORT}/webhooks/bigcommerce`);
  });
}
nextjs/app/webhooks/bigcommerce/route.ts
typescript
// Generated with: bigcommerce-webhooks skill
// https://github.com/hookdeck/webhook-skills

import { NextRequest, NextResponse } from 'next/server';
import { Webhook, WebhookVerificationError } from 'standardwebhooks';

// BigCommerce signs callbacks using the Standard Webhooks spec. The signing key
// is your app's CLIENT SECRET, base64-encoded. The standardwebhooks library
// base64-decodes whatever you pass in, so encoding the client secret first
// yields the raw client-secret bytes as the HMAC key.
function getWebhook(): Webhook {
  const clientSecret = process.env.BIGCOMMERCE_CLIENT_SECRET || '';
  return new Webhook(Buffer.from(clientSecret).toString('base64'));
}

interface BigCommerceEvent {
  store_id?: string;
  producer?: string;
  scope: string;
  data?: { type?: string; id?: number };
  hash?: string;
  created_at?: number;
}

export async function POST(req: NextRequest) {
  // Read the RAW body — verification must run over the exact bytes BigCommerce
  // signed, before any JSON parsing.
  const rawBody = await req.text();

  let event: BigCommerceEvent;
  try {
    event = getWebhook().verify(rawBody, {
      'webhook-id': req.headers.get('webhook-id') ?? '',
      'webhook-timestamp': req.headers.get('webhook-timestamp') ?? '',
      'webhook-signature': req.headers.get('webhook-signature') ?? '',
    }) as BigCommerceEvent;
  } catch (err) {
    if (err instanceof WebhookVerificationError) {
      console.error('BigCommerce webhook verification failed:', err.message);
      return new NextResponse('Invalid signature', { status: 400 });
    }
    console.error('Failed to process webhook:', err);
    return new NextResponse('Invalid payload', { status: 400 });
  }

  // BigCommerce payloads are thin: `scope` is the event, `data` carries only the
  // resource type and id. Call back to the REST API to fetch full details.
  const { scope, data } = event;

  switch (scope) {
    case 'store/order/created':
      console.log(`Order created: ${data?.id}`);
      // Your code: Fetch the order via GET /v2/orders/{id}, fulfil, notify
      break;

    case 'store/order/updated':
      console.log(`Order updated: ${data?.id}`);
      // Your code: Re-sync order details
      break;

    case 'store/order/statusUpdated':
      console.log(`Order status updated: ${data?.id}`);
      // Your code: Fetch order status, trigger fulfilment or refund flows
      break;

    case 'store/product/created':
      console.log(`Product created: ${data?.id}`);
      // Your code: Index the new product in your catalog
      break;

    case 'store/product/updated':
      console.log(`Product updated: ${data?.id}`);
      // Your code: Re-sync product details
      break;

    case 'store/product/deleted':
      console.log(`Product deleted: ${data?.id}`);
      // Your code: Remove the product from your catalog
      break;

    case 'store/product/inventory/updated':
      console.log(`Product inventory updated: ${data?.id}`);
      // Your code: Update stock levels downstream
      break;

    case 'store/customer/created':
      console.log(`Customer created: ${data?.id}`);
      // Your code: Sync customer to CRM / marketing list
      break;

    case 'store/cart/created':
      console.log(`Cart created: ${data?.id}`);
      // Your code: Track cart for analytics
      break;

    case 'store/cart/abandoned':
      console.log(`Cart abandoned: ${data?.id}`);
      // Your code: Trigger an abandoned-cart recovery email
      break;

    default:
      console.log(`Unhandled scope: ${scope}`);
  }

  // Respond 200 immediately so BigCommerce marks delivery successful.
  // Do heavy work asynchronously (queue) to avoid retries and blocklisting.
  return NextResponse.json({ received: true });
}
fastapi/main.py
python
# Generated with: bigcommerce-webhooks skill
# https://github.com/hookdeck/webhook-skills

import base64
import os

from dotenv import load_dotenv
from fastapi import FastAPI, Request, Response
from standardwebhooks.webhooks import Webhook, WebhookVerificationError

load_dotenv()

app = FastAPI()


def get_webhook() -> Webhook:
    """Build a Standard Webhooks verifier from the app's client secret.

    BigCommerce signs callbacks using the Standard Webhooks spec. The signing
    key is your app's CLIENT SECRET, base64-encoded. The standardwebhooks
    library base64-decodes whatever you pass in, so encoding the client secret
    first yields the raw client-secret bytes as the HMAC key.
    """
    client_secret = os.environ.get("BIGCOMMERCE_CLIENT_SECRET", "")
    encoded = base64.b64encode(client_secret.encode()).decode()
    return Webhook(encoded)


@app.post("/webhooks/bigcommerce")
async def bigcommerce_webhook(request: Request):
    # Read the RAW body — verification must run over the exact bytes
    # BigCommerce signed, before any JSON parsing.
    raw_body = await request.body()

    headers = {
        "webhook-id": request.headers.get("webhook-id", ""),
        "webhook-timestamp": request.headers.get("webhook-timestamp", ""),
        "webhook-signature": request.headers.get("webhook-signature", ""),
    }

    try:
        # verify() checks the HMAC-SHA256 signature over
        # `${webhook-id}.${webhook-timestamp}.${raw_body}`, enforces the
        # timestamp tolerance (replay protection), and returns the parsed JSON.
        # A malformed signature/header raises ValueError from base64 decoding;
        # treat it the same as a failed verification.
        event = get_webhook().verify(raw_body, headers)
    except (WebhookVerificationError, ValueError) as err:
        print(f"BigCommerce webhook verification failed: {err}")
        return Response(content="Invalid signature", status_code=400)

    # BigCommerce payloads are thin: `scope` is the event, `data` carries only
    # the resource type and id. Call back to the REST API to fetch full details.
    scope = event.get("scope")
    data = event.get("data") or {}
    resource_id = data.get("id")

    if scope == "store/order/created":
        print(f"Order created: {resource_id}")
        # Your code: Fetch the order via GET /v2/orders/{id}, fulfil, notify
    elif scope == "store/order/updated":
        print(f"Order updated: {resource_id}")
        # Your code: Re-sync order details
    elif scope == "store/order/statusUpdated":
        print(f"Order status updated: {resource_id}")
        # Your code: Fetch order status, trigger fulfilment or refund flows
    elif scope == "store/product/created":
        print(f"Product created: {resource_id}")
        # Your code: Index the new product in your catalog
    elif scope == "store/product/updated":
        print(f"Product updated: {resource_id}")
        # Your code: Re-sync product details
    elif scope == "store/product/deleted":
        print(f"Product deleted: {resource_id}")
        # Your code: Remove the product from your catalog
    elif scope == "store/product/inventory/updated":
        print(f"Product inventory updated: {resource_id}")
        # Your code: Update stock levels downstream
    elif scope == "store/customer/created":
        print(f"Customer created: {resource_id}")
        # Your code: Sync customer to CRM / marketing list
    elif scope == "store/cart/created":
        print(f"Cart created: {resource_id}")
        # Your code: Track cart for analytics
    elif scope == "store/cart/abandoned":
        print(f"Cart abandoned: {resource_id}")
        # Your code: Trigger an abandoned-cart recovery email
    else:
        print(f"Unhandled scope: {scope}")

    # Respond 200 immediately so BigCommerce marks delivery successful.
    # Do heavy work asynchronously (queue) to avoid retries and blocklisting.
    return {"received": True}


@app.get("/health")
async def health():
    return {"status": "ok"}


if __name__ == "__main__":
    import uvicorn

    uvicorn.run(app, host="0.0.0.0", port=8000)

From hookdeck/webhook-skills ↗

Or install the BigCommerce webhooks skill:

npx skills add hookdeck/webhook-skills --skill bigcommerce-webhooks

Common failures

Passing the client secret as it is

Standard Webhooks libraries base64-decode the secret they're given. BigCommerce's samples base64-encode the client secret first, so the signing key ends up as the secret's raw bytes. Skip that step and every signature fails.

Body parsed before verification

The signature covers the body as sent. A body you've parsed and re-serialized can differ by a single space and fail, so capture the raw bytes and verify before any body parser runs.

Treating `hash` as the signature

BigCommerce describes hash as a SHA-1 of the JSON-encoded payload data, for detecting duplicates. It takes no key, so a forged body can carry a matching one.

No signature headers on the delivery

BigCommerce's docs don't name the headers or say whether every webhook is signed, and the real deliveries Hookdeck has on file, from March 2023, have none. Log the headers on your first delivery. If they're missing, a custom header you set when creating the webhook is the documented alternative, though it's a shared value that doesn't cover the body.

From Hookdeck's BigCommerce guide

Let Event Gateway verify BigCommerce signatures.

Event Gateway verifies the signature on each BigCommerce delivery before it reaches your service, then queues it and retries failures on your schedule.

Not affiliated with BigCommerce. Facts are compiled from public sources and linked inline.