Receive and verify BigCommerce webhooks. Use when setting up BigCommerce webhook handlers, debugging Standard Webhooks signature verification, or handling store events like store/order/created, store/order/statusUpdated, store/product/updated, or store/cart/abandoned.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Receive and verify BigCommerce webhooks. Use when setting up BigCommerce webhook handlers, debugging Standard Webhooks signature verification, or handling store events like store/order/created, store/order/statusUpdated, store/product/updated, or store/cart/abandoned.
How do I handle store/order/created or store/order/statusUpdated events?
Why is my BigCommerce webhook signature verification failing?
How do I create a BigCommerce webhook via the API?
How BigCommerce Webhooks Work
BigCommerce webhooks are created via API only (no dashboard UI):
POST /stores/{store_hash}/v3/hooks with an X-Auth-Token OAuth access token.
Payloads are thin — data carries only the resource type and id. Read
the event from scope and call the REST API back to fetch the full resource:
{"store_id":
"1000"
,
"producer"
:
"stores/abc123"
,
"scope"
:
"store/order/statusUpdated"
,
"data"
:
{
"type"
:
"order"
,
"id"
:
173331
}
,
"hash"
:
"…"
,
"created_at"
:
1561479335
}
Respond HTTP 200 immediately; do slow work asynchronously. Failed deliveries
retry over ~48h, after which the hook is deactivated. If a domain's success
ratio drops below 90% in a 2-minute window it is blocklisted for 3 minutes.
Verification (core)
BigCommerce documents callback signing per the Standard Webhooks spec and
recommends verifying with Standard Webhooks libraries. The spec's headers are
webhook-id, webhook-timestamp, and webhook-signature (v1,<base64>),
with the signature computed as HMAC-SHA256 over
{webhook-id}.{webhook-timestamp}.{rawBody} — note BigCommerce's own docs
don't currently name the headers explicitly, state whether the feature is GA,
or clarify whether signatures apply to all hooks or only app-created hooks.
Log incoming headers on your first delivery to confirm. If signatures aren't
present on your hooks, fall back to custom headers set at hook creation
(see references/setup.md).
The signing key is your app's client secret, base64-encoded — the
standardwebhooks library base64-decodes whatever you pass, so encoding the
client secret first makes the raw client-secret bytes the HMAC key. Pass the
raw request body — don't JSON.parse first.
Node:
const { Webhook } = require('standardwebhooks');
// base64-encode the client secret; the library decodes it back to raw bytesconst wh = newWebhook(Buffer.from(process.env.BIGCOMMERCE_CLIENT_SECRET).toString('base64'));
const event = wh.verify(rawBody, { // rawBody = Buffer/string of the HTTP body'webhook-id': req.headers['webhook-id'],
'webhook-timestamp': req.headers['webhook-timestamp'],
'webhook-signature': req.headers['webhook-signature'],
});
// Throws WebhookVerificationError on tampering or a stale timestamp
Python:
import base64
from standardwebhooks.webhooks import Webhook
wh = Webhook(base64.b64encode(os.environ["BIGCOMMERCE_CLIENT_SECRET"].encode()).decode())
event = wh.verify(raw_body, { # raw_body = bytes of the HTTP body"webhook-id": headers["webhook-id"],
"webhook-timestamp": headers["webhook-timestamp"],
"webhook-signature": headers["webhook-signature"],
})
# Raises WebhookVerificationError on tampering or a stale timestamp
For complete handlers with route wiring, event dispatch, and tests, see:
BIGCOMMERCE_CLIENT_SECRET=your_client_secret # signs/verifies webhooks# Needed only to call the REST API back for full resource details:# BIGCOMMERCE_STORE_HASH=abc123# BIGCOMMERCE_ACCESS_TOKEN=your_access_token
Local Development
BigCommerce requires an HTTPS endpoint on port 443, so tunnel to your local
server. The Hookdeck CLI runs via npx — no install, no account required:
We recommend installing the webhook-handler-patterns skill alongside this one for handler sequence, idempotency, error handling, and retry logic. Key references (open on GitHub):
Handler sequence — Verify first, parse second, handle idempotently third
Idempotency — Prevent duplicate processing (use the payload hash field)
Error handling — Return codes, logging, dead letter queues
hookdeck-event-gateway - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers
