BigCommerce webhooks

BigCommerce webhooks are HTTPS POST requests that tell your app a store event happened, such as store/order/created, with the IDs involved but not the order, product or cart itself.

181 events covered

How BigCommerce webhooks work

Webhooks save you from polling the REST API for changes. You register a scope and a destination through the API, and each delivery is a small JSON body naming the scope, the store and a data object that usually holds only the resource's type and id. To read the order or product, call the REST API with that ID. A few scopes add a little more, such as the old and new status IDs on store/order/statusUpdated.

scope is how you tell events apart. Channel-specific scopes carry the channel's number in it, such as store/channel/1/order/created. BigCommerce's docs name no version for webhook bodies. Besides HTTPS, BigCommerce can deliver to Google Cloud Pub/Sub or Amazon EventBridge, and these pages cover HTTPS.

Key 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.

How events are identified
scope field in the body
Body format
JSON

Content type: application/json.

Send timestamp
webhook-timestamp

Reject deliveries older than 5 minutes.

Envelope
store_id, producer, scope, data, hash, created_at
Agent skill
npx skills add hookdeck/webhook-skills --skill bigcommerce-webhooks

Verify BigCommerce webhooks →

Setting up BigCommerce webhooks

  • Create a webhook with POST /stores/{store_hash}/v3/hooks or the GraphQL Admin API. The destination must be HTTPS on port 443, and a new webhook can take up to a minute to start working. Only the API account that created a webhook can see it.
  • To test locally, use a tunnel with a public HTTPS URL. See how to test BigCommerce webhooks on localhost.
  • GET /v3/hooks/admin lists your webhooks, your notification email addresses and any domains currently blocklisted. Set is_active back to true on the update endpoint to turn a webhook on again.
  • BigCommerce's docs describe no delivery log and no way to resend a callback. Recover missed events by fetching the data from the REST API.

Delivery behaviour

  1. Domain blocklisted

    If fewer than 90% of deliveries to a domain succeed in a two-minute window, BigCommerce blocklists that domain for your client_id for three minutes and queues events for retry. One failing endpoint affects all your webhooks on that domain.

    Blocklisting →
  2. Webhook deactivated

    After its last retry, about 48 hours after the first attempt, BigCommerce sets the webhook's is_active to false and emails the app's registered address. Subscriptions are also deactivated after 90 days of inactivity, so check is_active on a schedule.

    Deactivated webhooks →
  3. Duplicate deliveries

    BigCommerce can send the same callback more than once after network problems, outages or retries. Skip a delivery whose hash you've recently handled, and make your writes idempotent.

    Handle duplicates →
  4. No data in the body

    BigCommerce sends IDs rather than the resource, so most events need a REST API call to be useful. Those calls count against a quota that refills every 30 seconds, so a burst of events can get you rate limited.

    Thin payloads and rate limits →

BigCommerce webhook best practices

  • Verify every delivery. Use a Standard Webhooks library and your base64-encoded client secret. Anyone can compute the body's hash, so it proves nothing about the sender.
  • Respond straight away. BigCommerce says to send a 200 immediately and doesn't publish a timeout. Send no response body or extra headers, which it warns can interfere with acknowledgment.
  • Deduplicate on the hash. BigCommerce can send a callback more than once, and a repeat carries the same hash. Keep recent hashes for a short time and skip any you've already handled.
  • Watch for deactivated webhooks. Check is_active on a schedule, and subscribe store/hook/deliveryException at a separate destination so you hear about failures before retries run out.
  • Fetch resources at a controlled rate. Bodies carry IDs, so most events need an API call. Queue events and watch X-Rate-Limit-Requests-Left, because a burst of events can use up your quota.
  • Subscribe to specific scopes. BigCommerce advises against wildcards where you can name the scopes you handle. Each scope you drop is one less follow-up API call.

Common BigCommerce webhook events

Orders

store/order/created Order placed, including failed and unprocessed payments
store/order/updated Any change to an existing order
store/order/statusUpdated Order moves to a different status

Products

store/product/created New product added
store/product/updated Product attributes edited, globally or as a channel override
store/product/inventory/updated Base product stock level changes

Carts and customers

store/cart/abandoned Cart unchanged for at least an hour
store/cart/converted Cart becomes an order, usually after payment
store/customer/created New customer added

Events by resource

Resource Events Payloads
channel

store/channel/created · store/channel/updated · store/channel/metafield/created · store/channel/metafield/updated +63

67 52
company

store/company/created · store/company/updated · store/company/deleted · store/company/statusUpdated +11

15 4
product

store/modifier/updated · store/option/updated · store/product/deleted · store/product/created +9

13 13
cart

store/cart/created · store/cart/updated · store/cart/deleted · store/cart/couponApplied +8

12 12
price_list

store/priceList/created · store/priceList/updated · store/priceList/activated · store/priceList/deactivated +8

12 12
customer

store/customer/created · store/customer/updated · store/customer/deleted · store/customer/address/created +7

11 11
order

store/order/created · store/order/updated · store/order/archived · store/order/statusUpdated +7

11 11
store

store/hook/deliveryException · /app/uninstalled · /information/updated · /redirects/updated +3

7 6
category

store/category/created · store/category/updated · store/category/deleted · store/category/metafield/created +2

6 6
inventory

store/inventory/location/metafield/created · store/inventory/location/metafield/deleted · store/inventory/location/metafield/updated · store/inventory/location/created +2

6 6

6 more resources. All 181 events →

In this hub

Webhook events → Every covered BigCommerce event, with payloads where the registry has them.
MCP events → How an agent subscribes to BigCommerce events as MCP events.
Verify signatures → Signature facts, verification code and common failures.
Production guide → Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
Agent skill → Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill bigcommerce-webhooks

Keep a failing handler from blocklisting your BigCommerce domain.

Hookdeck Event Gateway accepts every BigCommerce delivery straight away, verifies the signature, queues events and retries to your service on your schedule, so a failure on your side doesn't count against your success rate or deactivate the webhook.

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