Webhooks Overview

Webhooks notify applications when specific events occur on a BigCommerce store. For example when:

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

This article is an overview of webhook behavior on BigCommerce. For a complete webhook API reference, see API Reference > Webhooks. For step-by-step webhooks tutorial on creating a webhook for certain store events, see Webhooks Tutorial.

Creating a webhook

To create a webhook, send a POST request to /stores/{{STORE_HASH}}/v2/hooks.

Webhooks POST request headers and body

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/hooks
X-Auth-Token: {{ACCESS_TOKEN}}
X-Auth-Client: {{CLIENT_ID}}
Content-Type: application/json
Accept: application/json

{
  "scope": "store/order/updated",
  "destination": "https://665b65a6.ngrok.io/webhooks",
  "is_active": true
}

Open in Request Runner

Response

{
  "client_id": "{{CLIENT_ID}}",
  "created_at": 1580329317,
  "destination": "https://665b65a6.ngrok.io/webhooks",
  "headers": null,
  "id": 20172984,
  "is_active": true,
  "scope": "store/order/*",
  "store_hash": "{{STORE_HASH}}",
  "updated_at": 1580329317
}

Note

Following the creation of a webhook, it can take up to one minute for BigCommerce to start making POST requests to the destination server.

Callback payload

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

statusUpdated POST request body

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

A request can then 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 a callback has been received without issue, the destination server must return an HTTP 200 response — no response, or 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. Doing otherwise triggers BigCommerce’s callback retry mechanism.

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, a success ratio is calculated.

The following process will determine whether the destination URI gets blacklisted:

  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 for 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, BigCommerce takes the following precautions:

  • Webhook payloads contain minimal information about the store and event
  • Webhook payloads are sent over TLS-encrypted connection
  • Create Webhook requests accept an optional header object which can be used to authenticate callbacks requests

POST requests that includes header object

{
"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 200 response when making POST to /hooks

  • Check TLS/SSL configuration on machine making POST request.
  • Verify POST request contains the required HTTP headers:

Create hook POST request

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