BigCommerce webhooks in production: duplicates, ordering, retries and timeouts
This guide covers the problems BigCommerce webhooks cause in production and how to handle each one. What BigCommerce sends is on the BigCommerce webhooks overview, every scope is on BigCommerce webhook events, and signature verification code is on Verify BigCommerce webhooks.
At a glance
| Problem | What to do | With Event Gateway |
|---|---|---|
| Timeouts | Send an empty 200 immediately; process in a background job | Accepts the delivery at once, then queues it for your service |
| Duplicates | Skip a hash you've recently handled; make writes idempotent | Drops repeats before they reach your handler |
| Ordering | Don't rely on arrival order; fetch current state from the REST API | Logs every event and attempt, so you can see arrival order when debugging |
| Retries and blocklisting | Check is_active; subscribe to store/hook/deliveryException; reconcile after outages | Keeps your success rate up while your service is down, then retries |
| Choosing scopes | Name the scopes you handle; use data filters for metafields | Filters and routes events by scope |
| Testing | Use a public HTTPS tunnel on port 443; trigger real store changes | Forwards to localhost and replays past events |
| Other limits | Queue API calls against your rate limit; retry a 404 before giving up | Delivers at a rate you set, with an optional delay |
BigCommerce webhook timeouts and slow handlers
Send a 200 as soon as you've received the request, then do the work in a background job. BigCommerce doesn't publish a timeout, so there's no safe number to design to.
Why it happens: BigCommerce's advice for webhooks that time out is to send a success status immediately. No response, or a response outside the 200 range, counts as a failed delivery and starts the retry schedule. Each failure also lowers the success rate for your whole domain, so a slow handler can get the domain blocklisted.
Keep the response itself small. BigCommerce doesn't recommend sending a body or headers, because they can interfere with acknowledgment. If you do send headers, each value should stay under 8 KB and each name under 64 characters, with no more than 64 headers.
Fix it in your handler:
- Verify the signature and return
200with an empty body. - Push the event onto a queue and process it in a worker. See why to process webhooks asynchronously.
- Make your REST API calls from the worker, never before you respond.
With Event Gateway: Hookdeck accepts each BigCommerce delivery immediately, then queues events and delivers them to your service at a rate it can handle, with its own retries. Your handler can take as long as it needs without failing a BigCommerce delivery.
Duplicate BigCommerce webhooks
BigCommerce can send the same callback more than once. Skip a delivery whose hash you've recently handled, and make your writes idempotent.
Why it happens: BigCommerce names three causes: network problems, its own systems resending events as they recover from an outage, and retries. A retry can repeat an event you've already processed if your 200 didn't reach BigCommerce. The docs say a hook that fires twice for one event carries the same hash, which they define as the SHA-1 hash of the JSON-encoded payload data.
BigCommerce's tutorial adds that a matching hash can also appear when the same properties of a product are updated several times in a short period. Those are separate changes with one hash, so keep hashes for a short time rather than forever. Because the body holds only IDs, skipping one of them loses nothing as long as you fetch current state when you act.
Fix it in your handler:
- Check the
hashbefore processing, and store it with a short expiry. BigCommerce suggests the same approach. See how to implement webhook idempotency. - Write with upserts keyed on the resource ID, so processing an event twice gives the same result.
- Before a side effect such as sending an email, check whether the state it depends on has actually changed.
def handle_bigcommerce_delivery(event):
# Same hash handled in the last 10 minutes
if not cache.set(f"bc_hash_{event['hash']}", True, nx=True, ex=600):
return
process(event)
With Event Gateway: Hookdeck deduplicates events before they reach your endpoint, on the whole payload or on fields you choose, so repeats are filtered at the infrastructure level rather than in each handler.
Out-of-order BigCommerce webhooks
BigCommerce's docs make no promise about delivery order, so don't rely on it. Fetch the resource's current state from the REST API instead of inferring it from the sequence of events.
Why it happens: A delivery that fails goes on a schedule whose gaps reach 24 hours, and events sent during a blocklist wait in a retry queue. Newer events keep arriving in the meantime, so an old event can land long after a later one. BigCommerce describes created_at only as the hook's creation date, so it isn't a documented way to put events in order.
Thin bodies make this easier to live with, since most of them say only that something changed. Some scopes fire together as well: creating a cart also fires store/cart/updated, and removing its last item fires store/cart/updated too.
Fix it in your handler:
- Treat each event as a prompt to read the resource from the REST API, and act on what the API returns.
- Handle
store/order/statusUpdatedby comparingprevious_status_idwith the status you hold. A mismatch means you missed an event or received it late, so fetch the order. - Treat a 404 after a
deletedevent, or afterstore/cart/converted, as expected. BigCommerce says a converted cart has already been deleted, and its body includes the order ID to use instead.
With Event Gateway: Hookdeck logs every event and delivery attempt, so when state looks wrong you can see the order events actually arrived in and replay them.
BigCommerce webhook retries, blocklisting and deactivation
BigCommerce retries a failed delivery 11 times over about 48 hours, then deactivates the webhook. Separately, a low success rate blocklists your domain for three minutes. Monitor for both, and reconcile from the REST API after any outage.
Why it happens: The retries come at increasing intervals:
| Retry | Wait |
|---|---|
| 1 | 60 seconds |
| 2 | 3 minutes |
| 3 | 5 minutes |
| 4 | 10 minutes |
| 5 | 15 minutes |
| 6 | 30 minutes |
| 7 | 1 hour |
| 8 | 2 hours |
| 9 | 6 hours |
| 10 | 14 hours |
| 11 | 24 hours |
After the last one, BigCommerce sets is_active to false and emails the address registered for the app. Nothing more is delivered until you turn the webhook back on, and BigCommerce's docs describe no way to resend what was missed. A webhook is also deactivated after 90 days of inactivity, which the docs don't define further.
Blocklisting. BigCommerce tracks a success rate for each destination domain over a sliding two-minute window, once 100 requests have gone out in that window. If it falls below 90%, the domain is blocklisted for three minutes. Events fired during that time go to the retry queue and follow its schedule. The block applies to your client_id rather than to every app using the domain, but it does cover all your webhooks on that domain: domain.com/webhook-1 and domain.com/webhook-2 count together, so one broken endpoint can hold up the other.
Fix it in your handler:
- Subscribe to
store/hook/deliveryException. It fires with error code90001when a delivery failed and will be retried (at most once in 10 minutes per destination),90002when retries are exhausted and the webhook is about to be disabled, and90003when the domain is blocked. Its destination must differ from all your other webhook destinations, and each store and client gets only one. - Call
GET /v3/hooks/adminon a schedule. It returns your webhooks with theiris_activeand status, your notification email addresses, and any blocked domains with the time left. Add addresses you actually monitor. - After a fix, set
is_activeback totruewith the update endpoint. - Reconcile on a schedule and after every outage, because deactivation drops events rather than holding them.
- Handle errors in your own worker, and return
200from the endpoint even when processing later fails. A failure you report to BigCommerce counts against your whole domain.
With Event Gateway: Hookdeck accepts every BigCommerce delivery while your services are down, so your success rate stays up and the webhook isn't deactivated. Failed events can be retried automatically or replayed in bulk after you fix the problem.
Choosing BigCommerce scopes
Subscribe to the specific scopes you handle. Every delivery you don't need still costs you a request to acknowledge, and BigCommerce itself advises against wildcards where you can name scopes.
Why it happens: Wildcards such as store/order/* are supported only where BigCommerce's reference lists them, and other patterns return a 422. They also bring in scopes that read alike but differ. store/order/updated fires on any change to an order, including a status change, while store/order/statusUpdated fires only when the status changes. store/cart/updated fires when the cart's first item is added, so it comes with store/cart/created. store/customer/updated doesn't track changes to the customer's addresses.
Choose this way:
- Pick the narrowest scope that tells you what you need, such as
store/order/statusUpdatedrather thanstore/order/updated. - For a store with several channels, subscribe to the channel's own scope, such as
store/channel/1/order/created. The channel-scoped cart abandoned event gives an abandoned cart record ID rather than the cart ID, so usestore/cart/abandonedwhen you need the real one. - To cut metafield traffic, add a data filter on the metafield
namespacethrough the GraphQL Admin API. The REST webhook endpoints don't support them, and each webhook takes one filter with one value. - Plan for the limits: 10 webhooks per store, client and scope, and only one for each store, client, scope and destination.
With Event Gateway: Hookdeck can filter and route events by scope or any body field, so each service sees only what it handles, whichever scopes the webhook subscribes to.
Testing BigCommerce webhooks
Test against a public HTTPS URL by making real changes in a store. BigCommerce needs port 443 and a valid certificate, so a plain localhost address won't work.
Why it happens: Destinations must serve TLS on port 443, and custom ports aren't supported. Self-signed certificates, a hostname that doesn't match the certificate, or missing intermediate certificates all fail the TLS handshake and count as failed deliveries. A new webhook can also take up to a minute to start working, so a test run straight after creating one can look broken.
Test it this way:
- Point a webhook at a tunnel, such as the Hookdeck CLI. See how to test BigCommerce webhooks on localhost.
- Wait a minute, then trigger the event by editing a product or placing a test order.
- Log the request headers on your first delivery. BigCommerce's docs name the Standard Webhooks spec without naming the headers, so confirm what your handler receives.
- Add a
store/hook/deliveryExceptionwebhook to your test setup, then return errors from your handler to watch the retries and error codes. - Use the same API account throughout. Webhooks created with one token aren't visible through another, so a webhook can look missing when it isn't.
With Event Gateway: The Hookdeck CLI forwards events to localhost, and you can replay past events to your local or production handler without changing anything in the store.
Other BigCommerce webhook limits
Thin payloads and rate limits. Bodies carry IDs, not the resource, so most events need a REST API call. For OAuth apps, the quota refills every 30 seconds and depends on the plan, with Growth and Core at 150 requests per window and Scale at 450. A burst of order events can use that up. Fetch from a queue at a controlled rate, watch X-Rate-Limit-Requests-Left, and wait for X-Rate-Limit-Time-Reset-Ms when you hit the limit. Cache resources you read often, and fetch only for the events you act on.
A 404 straight after an event. BigCommerce's docs don't say how soon a resource can be read after its event. Retry a 404 a few times with a short backoff before treating it as permanent, except after the deleted and converted events covered under ordering.
Which webhooks you can see. A webhook is visible only to the API account that created it, and there's no documented way to list every webhook on a store across accounts. Keep your own record of which account owns which subscription. Deleting an API account removes its webhooks for good, and BigCommerce deletes an app's webhooks when the app is uninstalled.
No delivery log. BigCommerce's docs describe no log of delivery attempts, and store/hook/deliveryException is itself a webhook that can fail. Log what you receive so you have a record when something goes missing.
With Event Gateway: Hookdeck delivers at a max delivery rate that you can match to your API quota, and a delay rule can hold events before forwarding them. Its dashboard shows every event and attempt, with a full request and response history.
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.