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 webhook API reference, see API Reference > Webhooks. For webhook event reference, see Webhook Events. For a step-by-step tutorial on creating webhooks for certain store events, see Webhooks Tutorial.

Creating a webhook

To create a webhook, send a POST request to the Create a webhook endpoint. Set the scope property value equal to the Name / Scope of the webhook you want to create.

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/hooks
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "scope": "store/order/updated",
  "destination": "https://yourapp.example.com/webhooks", // custom ports are not supported
  "is_active": true,
  "headers": {}
}

{
  "created_at": 1580329317,
  "destination": "https://yourapp.example.com/webhooks", // custom ports are not supported
  "headers": null,
  "id": 20172984,
  "is_active": true,
  "scope": "store/order/updated",
  "store_hash": "{{STORE_HASH}}",
  "updated_at": 1580329317
}

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.

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

You can then make a request to the Get an order endpoint 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.

Response requirements

BigCommerce doesn't recommend sending bodies or headers in response to webhooks. It may interfere with the webhook delivery acknowledgment.

BigCommerce has the following webhook response requirements:

If you send response headers, they must conform to the following limitations for the webhook delivery to be successfully acknowledged:

• The header value should not exceed 8 kilobytes (10 by 1 kilobytes is OK).
• The header name should not exceed 64 characters (bytes).
• The total number of headers shouldn't exceed 64.

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

1. Once a webhook is triggered, the service checks if your callback URI is on the blocklist.
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 blocklisted for three minutes.
4. Some webhook events triggered during this time are sent to our retry queues for execution later after the domain per specific client_id is no longer blocklisted and once the retry queue time has elapsed.

Blocklisting occurs to the specific client_id, not the entire domain. The webhook service can execute requests for a client_id with less traffic or properly formed requests while blocklisting another client_id on the same domain.

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

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 using the Update a webhook endpoint.

Post app uninstall actions

To avoid accumulating unused webhooks, BigCommerce automatically deletes registered webhooks on app uninstall.

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 to accept an optional header object which can be used to authenticate callbacks requests.

POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/hooks
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
 
{
  "scope": "store/cart/lineItem/*",
  "destination": "https://yourapp.example.com/webhooks", // custom ports are not supported
  "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 with 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, send a request to the Get a webhook endpoint 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://globalsign.ssllabs.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 using the Update a webhook endpoint, so that BigCommerce starts sending event callback requests again.

No 200 response from the Create a webhook endpoint

• Check TLS/SSL configuration on the computer sending the request.
• Verify POST request contains the following required HTTP headers:

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

Unable to view your webhook

Webhooks created with one token are not visible when you retrieve webhooks using a different token. To view your webhook, use the same account token that created the webhook.

Webhooks timing out

To prevent your webhooks from timing out, send a 200 success status response immediately after receiving the request.

Duplicate webhook events

Duplicate webhooks can happen. For this reason, apps should use idempotent operations to avoid significant unintended side effects. Idempotent operations allow multiple calls without changing the result. A way to ensure webhook events are idempotent is to create a temporary "blocklist" array to store the hash of webhooks that have already been received or handled. When you receive a webhook, you can compare the hash of the received event to the list. If the hash has already been handled you can ignore the event.

Tools

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

Related resources

Articles

• Webhook Tutorial
• Webhook Events

Endpoints

• Webhooks Reference