# BigCommerce webhooks in production: duplicates, ordering, retries and timeouts

Agent skill: `npx skills add hookdeck/webhook-skills --skill bigcommerce-webhooks` ([details](https://hookdeck.com/webhooks/bigcommerce/skill))

This guide covers the problems BigCommerce webhooks cause in production and how to handle each one. What BigCommerce sends is on the [BigCommerce webhooks](/webhooks/bigcommerce) overview, every scope is on [BigCommerce webhook events](/webhooks/bigcommerce/events), and signature verification code is on [Verify BigCommerce webhooks](/webhooks/bigcommerce/verify).

## At a glance

| Problem | What to do | With Event Gateway |
| --- | --- | --- |
| [Timeouts](#timeouts) | Send an empty `200` immediately; process in a background job | Accepts the delivery at once, then queues it for your service |
| [Duplicates](#duplicates) | Skip a `hash` you've recently handled; make writes idempotent | Drops repeats before they reach your handler |
| [Ordering](#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](#retries) | 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](#choosing-events) | Name the scopes you handle; use data filters for metafields | Filters and routes events by scope |
| [Testing](#testing) | Use a public HTTPS tunnel on port 443; trigger real store changes | Forwards to localhost and replays past events |
| [Other limits](#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 {#timeouts}

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](#retries).

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:**

1. Verify the signature and return `200` with an empty body.
2. Push the event onto a queue and process it in a worker. See [why to process webhooks asynchronously](/webhooks/guides/why-implement-asynchronous-processing-webhooks).
3. 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 {#duplicates}

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:**

1. Check the `hash` before processing, and store it with a short expiry. BigCommerce suggests the same approach. See [how to implement webhook idempotency](/webhooks/guides/implement-webhook-idempotency).
2. Write with upserts keyed on the resource ID, so processing an event twice gives the same result.
3. Before a side effect such as sending an email, check whether the state it depends on has actually changed.

```python
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](/docs/deduplication) 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 {#ordering}

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:**

1. Treat each event as a prompt to read the resource from the REST API, and act on what the API returns.
2. Handle `store/order/statusUpdated` by comparing `previous_status_id` with the status you hold. A mismatch means you missed an event or received it late, so fetch the order.
3. Treat a 404 after a `deleted` event, or after `store/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 {#retries}

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:**

1. Subscribe to `store/hook/deliveryException`. It fires with error code `90001` when a delivery failed and will be retried (at most once in 10 minutes per destination), `90002` when retries are exhausted and the webhook is about to be disabled, and `90003` when the domain is blocked. Its destination must differ from all your other webhook destinations, and each store and client gets only one.
2. Call `GET /v3/hooks/admin` on a schedule. It returns your webhooks with their `is_active` and status, your notification email addresses, and any blocked domains with the time left. Add addresses you actually monitor.
3. After a fix, set `is_active` back to `true` with the update endpoint.
4. Reconcile on a schedule and after every outage, because deactivation drops events rather than holding them.
5. Handle errors in your own worker, and return `200` from 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](/docs/retries) automatically or replayed in bulk after you fix the problem.

## Choosing BigCommerce scopes {#choosing-events}

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:**

1. Pick the narrowest scope that tells you what you need, such as `store/order/statusUpdated` rather than `store/order/updated`.
2. 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 use `store/cart/abandoned` when you need the real one.
3. To cut metafield traffic, add a data filter on the metafield `namespace` through the GraphQL Admin API. The REST webhook endpoints don't support them, and each webhook takes one filter with one value.
4. 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](/docs/filters) events by `scope` or any body field, so each service sees only what it handles, whichever scopes the webhook subscribes to.

## Testing BigCommerce webhooks {#testing}

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:**

1. Point a webhook at a tunnel, such as the [Hookdeck CLI](/docs/cli). See [how to test BigCommerce webhooks on localhost](/webhooks/platforms/how-to-test-and-replay-bigcommerce-webhook-events-on-localhost-with-hookdeck).
2. Wait a minute, then trigger the event by editing a product or placing a test order.
3. 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.
4. Add a `store/hook/deliveryException` webhook to your test setup, then return errors from your handler to watch the retries and error codes.
5. 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 {#other-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](#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](/docs/destinations#set-a-max-delivery-rate) that you can match to your API quota, and a [delay rule](/docs/connections#delay-rule) can hold events before forwarding them. Its dashboard shows every event and attempt, with a full request and response history.