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
webhook-signature Format: v1,<base64> (space-separated when more than one)
{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.
Verify with a Standard Webhooks library, passing the client secret base64-encoded 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
// 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`);
});
} // 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 });
} # 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) 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.
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.