Are you developing an app for BigCommerce? If so, then you should know how to use webhooks.
Webhooks allow you to “subscribe” to events, which means your app will be notified immediately when these events happen in a BigCommerce store. Then, you can set up your app so that certain actions are triggered when a subscribed event occurs.
For example, webhooks are what make it possible for users of the BigCommerce for WordPress app to update the BigCommerce product inventory that’s displayed on their WordPress site without having to manually press a sync button.
Indeed, just about any kind of BigCommerce app, from page builders to data transfer services to order management tools, can expand their capabilities with this powerful resource.
Create customized pages in BigCommerce with ShogunBuild dynamic pages that convert shoppers into customers. Get started now
BigCommerce webhooks use OAuth for authentication, and they support the JSON media type (basic auth and XML are not supported).
You’ll need to have the following before you’re able to send and receive requests with webhooks:
If you don’t already have a BigCommerce account, you can join the BigCommerce Partnership Program in order to get access to a free sandbox store. This will save you a good bit of money, as it eliminates the need to purchase a BigCommerce membership (plans start at $29.95 per month after a 15-day free trial).
To qualify for the BigCommerce Partnership Program, you’ll need:
Go to the BigCommerce Partner page to apply.
After you’ve been approved, follow these steps to create your sandbox store:
1. Go to bigcommerce.com and select “Log In”.
2. Click on the “Get Started” link below the “Log In” button.
3. Select “Start Your Free Trial”.
4. Fill out the information needed to create your new store (be sure to enter the same email address that you used to submit your partnership application). At this moment, your store is in a standard trial period.
5. Now that you’ve been approved for the BigCommerce Partnership Program and you have a BigCommerce account, you can sign in to the BigCommerce Partner Portal.
Here, you can request converting your new store into a sandbox. The BigCommerce team will flag your store so that the 15-day trial period no longer applies to you and you can continue to use your free store indefinitely. It usually takes about two days for this status to be applied.
After you log in to the BigCommerce Partner Portal, you’ll also be able to create an API account for your app. This will generate the OAuth Client ID and OAuth token that you need to continue.
If you have a self-signed certificate or intermediate certificates are not able to load on your app server, this will cause a connection failure. You can check your TLS/SSL certificate status at SSL Labs.
When a subscribed event happens in BigCommerce, you’ll be sent a payload that only contains the minimum amount of details regarding the event. Keeping details to a minimum in the payload helps improve security, as a user would need to be completely authenticated to access the full details. It also gives you a lot of flexibility with how you manage the notification in your app.
The elements of each payload include:
The BigCommerce webhook example below shows what this payload looks like:
You’ll need to include the following in the HTTP headers of webhook requests:
Accept: application/json
Content-Type: application/json
X-Auth-Client: (your OAuth client id)
X-Auth-Token: (your OAuth token)
A webhook response contains the following elements:
An HTTP 201 response confirms that your BigCommerce webhook setup was successful.
Note that there is a one-minute timeout in place, so you might need to wait for up to one minute before the callback URI on your server starts to receive requests.
An HTTP response outside the 200 range will indicate that the webhook was not received.
Every instance that a HTTP 201 response is returned is counted as a success, and every instance that there is no response or the server times out is counted as a failure.
If your ratio of successes to failures falls below 90% at any point within a two-minute window, your domain will be blacklisted for three minutes. There is a minimum threshold count of 100 webhook requests, meaning that the first 100 requests in a two-minute window will not count toward your success/failure ratio regardless of the responses.
When a domain has been blacklisted, the BigCommerce webhook dispatcher will attempt retries at increasing intervals (note that the retires are triggered by your entire domain rather than specific webhooks – the success/failure ratio for each of your webhooks will be calculated into your overall rate):
If that twelfth and final retry doesn’t do the trick, your webhook will be deactivated and you’ll be sent an email notification about the issue. After you fix the problem, you’ll need to manually set “is_active” back to “true” to reactivate the webhook.
After your domain is removed from the blacklist, new requests will be sent in real-time. Requests that were sent when your domain was blacklisted will be re-sent as they were queued.
There are many different events that you can subscribe to with webhooks, which opens up a lot of possibilities for your app.
Order-related events that you can subscribe to include:
Product-related events that you can subscribe to include:
Category-related events that you can subscribe to include:
SKU-related events that you can subscribe to include:
Customer-related events that you can subscribe to include:
Store-related events that you can subscribe to include:
Cart-related events that you can subscribe to include:
Cart line item-related events that you can subscribe to include:
Shipment-related events that you can subscribe to include:
Subscriber-related events that you can subscribe to include:
BigCommerce recommends that you use ngrok to test out your webhooks while you’re developing your integration.
With ngrok, you’re able to set up a tunnel between your localhost server and a public URL. It also gives you access to a web interface for viewing HTTP request details. That way, you can make sure your integration is running smoothly before you release it.
Create customized pages in BigCommerce with ShogunBuild dynamic pages that convert shoppers into customers. Get started now