BigCommerce Webhooks

  • Version: 2.0
  • Host: api.bigcommerce.com/stores/store_hash/v2
  • Protocols: https
  • Accepts: application/json
  • Responds With: application/json
More Info

Webhooks allow applications to be notified when specific events occur on a BigCommerce store. For example when:

  • an order is created,
  • a product’s inventory changes, or
  • an item is added to a shopper’s cart.

OAuth Scopes

UI Name Permission Parameter
Information & Settings modify store_v2_information
Information & Settings read-only store_v2_information_read_only

For more information on OAuth Scopes, see: Authentication.

Authentication

Requests can be authenticated by sending a client_id and access_token via X-Auth-Client and X-Auth-Token HTTP headers:

GET /stores/store_hash/v3/catalog/summary
host: api.bigcommerce.com
Accept: application/json
X-Auth-Client: {client_id}
X-Auth-Token: {access_token}
Header Parameter Description
X-Auth-Client client_id Obtained by creating an API account or installing an app in a BigCommerce control panel.
X-Auth-Token access_token Obtained by creating an API account or installing an app in a BigCommerce control panel.

For more information on Authenticating BigCommerce APIs, see: Authentication.

Available Endpoints

Resource Description
Webhooks Manage store Webhooks

Callback Payload

When a webhook is triggered, BigCommerce will POST a light payload containing minimum event details to the destination server. For instance, the data object for store/order/statusUpdated contains only the order id:

{
 "store_id":11111,
 "producer":"stores/abcde",
 "scope":"store/order/statusUpdated",
 "data":{
         "type":"order",
         "id":173331
        },
 "hash":"3f9ea420af83450d7ef9f78b08c8af25b2213637"
 }

A subsequent request can be made to /orders/{id} to obtain full order details.

For more information on specific webhook events and their payloads, see Webhook Events.

Handling Callbacks

To acknowledge the callback has been received without issue, the destination server must return an HTTP 200 response – any response outside the 200 range indicates the callback was not received. If this happens, the webhook service will use the retry mechanism described below.

Need to set up a quick webhook destination URL for testing? See Tools for Debugging and Testing Webhooks.

Callback Retry Mechanism

The webhooks service will do its best to deliver events to the destination callback URI. It is best practice for the application to respond to the callback before taking any other action that would slow its response. If an app server responds to a webhook payload with anything other than a 2xx response, or times out and indicates the payload has not been received, the following process will determine whether the destination URI gets blacklisted.

The webhook service may send many payloads to a single URI in quick succession. Because of this, we use a sliding scale across a two minute window to calculate a callback response success rate for each remote destination. When the webhook service receives a 2xx response, the destination’s success count is increased. If there’s no response or the remote server times out, the destination’s failure count is increased. Based on these two numbers, the success ratio is calculated.

The webhook service flow is as follows:

  1. Once a webhook is triggered, the service checks if your callback URI is on the blacklist
  2. If it’s not, we calculate a success ratio for the remote server based on its success/failure count in a two minute window
  3. If at any point in the two minute window the success/failure ratio dips below 90%, the destination URI’s domain will be blacklisted for three minutes
  4. Webhook events triggered during this time are sent to our retry queues to be executed later when the domain is no longer blacklisted and once the retry queue time has elapsed.

Once a domain is no longer blacklisted, all new webhook requests will be sent as they occur. Event requests sent to the retry queue during a blacklisting period will be delivered according to the retry queue schedule.

The webhook dispatcher will then attempt several retries (at increasing intervals) until the maximum retry limit is reached.

Retry Intervals:

  • 60 seconds after the most recent failure
  • 180 seconds after the most recent failure
  • 180 seconds after the most recent failure
  • 300 seconds after the most recent failure
  • 600 seconds after the most recent failure
  • 900 seconds after the most recent failure
  • 1800 seconds after the most recent failure
  • 3600 seconds after the most recent failure
  • 7200 seconds after the most recent failure
  • 21600 seconds after the most recent failure
  • 50400 seconds after the most recent failure
  • 86400 seconds (24 hours) after the most recent failure

After the final retry attempt (cumulatively 48 hours after the first delivery attempt), the webhook will be deactivated, and an email will be sent to the email address registered on the subscribing app. To reactivate the webhook, set is_active back to true by making a PUT request to /hooks/{id}.

Note

  • A domain’s success rate for a given sliding window is not calculated until 100 webhook requests are sent – this means the domain will not be blacklisted for the first 100 webhooks sent within the time window (regardless of response) as all webhooks are sent until the minimum threshold has been reached for the current time window.
  • The webhook dispatcher determines whether retries are needed based on responses from the subscribed domain as a whole, not by specific hooks. For example, domain.com/webhook-1 and domain.com/webhook-2 will affect each other for failures and retries, as both URLs belong to the same domain.

Security

To ensure webhook callback requests are secure:

  1. Webhook payloads contain minimal information about the store and event
  2. Webhook payloads are sent over TLS-encrypted connection
  3. Create Webhook requests accept an optional headers objects which can be used to authenticate callbacks requests:
{
"scope": "store/cart/lineItem/*",
  "destination": "{{DESTINATION_URL}}",
  "is_active": true,
  "headers": {
  	"Username": "Hello",
  	"Password": "Goodbye"
  }
}

BigCommerce will send the specified headers when making callback requests to the destination server – this allows webhook destination URIs to be secured via basic authentication.

Troubleshooting

Not receiving Webhook Event Callbacks

If your app does not return an HTTP 200 to BigCommerce after receiving the webhook event payload, BigCommerce considers it a failure. BigCommerce will keep trying for a little over 48 hours. At the end of that time, BigCommerce sends an email to the email address set during app registration and disables the webhook by setting the is_active flag to false.

To see if a webhook is still active, make a GET request to /hooks/{id} and check the value of the is_active property in the response.

If you receive an email, or discover is_active is false, try the following:

  • Verify the app is responding to the callback with a 200 response.
  • Verify the destination server has a valid TLS/SSL setup by visiting https://sslcheck.globalsign.com. Any of the following will cause the TLS/SSL handshake to fail:
    • Self-signed certificates
    • Hostname on certificate doesn’t match the hostname in DNS settings
    • Key and trust stores are not configured with the required intermediate certificates.

Once the issue is resolved, set is_active to true by making a PUT request to /hooks/{id} – BigCommerce start sending event Callback requests again.

No 201 response when making POST to /hooks

  • Check TLS/SSL configuration on machine making POST request.
  • Verify POST request contains the required HTTP headers:
POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/hooks
Accept: application/json
Content-Type: application/json
X-Auth-Token: {{ACCESS_TOKEN}}
X-Auth-Client: {{CLIENT_ID}}

Tools

Below is a collection of third-party tools that can be used to aid in the development, testing, and debugging of webhooks:

Tool Description
ngrok Easily set up tunnels between localhost and an ngrok public URL to test callback requests on your machine
Webhook Tester Test webhooks and other types of HTTP requests in your browser

Resources