bigcommerce-webhooks

BigCommerce Webhooks

When to Use This Skill

• How do I receive BigCommerce webhooks?
• How do I verify BigCommerce webhook signatures?
• 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.