BigCommerce order webhooks: how they fail, retry and get deactivated

What a BigCommerce webhook is promising

A BigCommerce webhook is a short notification that something happened, sent to an address you registered. For orders, the documentation names scopes such as an order being updated or its status being updated. The notification is deliberately light: it carries an identifier, not the order, so the receiver is expected to fetch the details from the API. That design puts the load on the receiver, and it is the receiver's answers that decide whether BigCommerce keeps sending.

• The notification says that something changed, not what the order contains.
• A receiver that fails to fetch the order after acknowledging loses it silently.

What counts as a good answer

BigCommerce requires an HTTP 200 response. No response, or one outside the 200 range, is treated as not received. The destination must use port 443; custom ports are not supported. The documentation gives no response time limit, but advises answering immediately, before any other work, to avoid timeouts. Headers and bodies in the response are unnecessary and discouraged. The practical rule for the receiver is therefore: write down the notification, answer 200 straight away, and do the processing afterwards.

• A redirect, a 4xx or 5xx status, and a timeout are all failures from BigCommerce's point of view.
• A receiver that does slow work before answering invites timeouts.

The retry schedule and how a webhook ends up deactivated

BigCommerce measures success over a sliding two-minute window. When the success rate falls below 90 percent, and after at least 100 requests in the window, that client is blocklisted for three minutes; this is judged per domain, not per webhook. Notifications that were held back are retried at increasing intervals: 11 retries from 60 seconds up to 86,400 seconds, over a cumulative 48 hours. After the last retry the webhook is deactivated and an email is sent to the registered address of the subscribing app.

That email matters, because the person who receives it may not be the store owner. A webhook is also deactivated after 90 days of inactivity, and webhooks are deleted outright when the app is uninstalled or the API account is deleted. Reactivation after a deactivation is an update that sets the active flag back to true; deletion needs a new subscription.

• 48 hours of retries, then deactivation.
• Orders placed after deactivation are never announced.
• The documentation describes no replay of notifications missed while a webhook was inactive.

Duplicates, limits and timing

Duplicates can occasionally occur, from network glitches or retries, so a receiver should keep a temporary list of the hash values it has processed and ignore repeats. A store can have at most 10 webhooks per store, client and scope, and only one per scope and destination. A new webhook can take up to a minute to start working. Do not assume notifications arrive in order; the documentation makes no promise about ordering.

A safe first investigation

Start with evidence you own. You need the time the connected system last received an order, the list of order IDs BigCommerce holds for the days since, and the list the connected system holds.

• Find the first missing order: its time marks the start of the gap, and 48 hours before it is when retries began.
• Ask whoever created the API account whether an email about a deactivated webhook arrived.
• List the store's webhooks and read the active flag and destination for each.
• Check the receiver: does it answer 200 immediately, over the standard port, with no redirect?
• Never share API credentials in an email; the person who owns the account runs the list and re-activation.

What fixes it, and what does not fit

Fix the receiver first, then reactivate. If the receiver still fails after reactivation, the webhook will deactivate again after another 48 hours. Then close the gap: The documentation describes no replay of notifications missed while a webhook was inactive, so compare order ID lists and load the missing orders into the connected system. If the webhook was deleted because an app was uninstalled, a new subscription is needed, which is a larger rebuild. A third-party receiver you cannot change is its vendor's to fix.

How the paid fix is accepted

The fixed job for this problem is accepted on a copy of your receiver with synthetic notifications. It answers 200 before processing and records each notification, a notification sent twice produces one record, a burst of notifications is all acknowledged with no error status, and a gap list names every order in the store that is absent from the connected system. You run the re-activation under your own account; we never receive your credentials.