BigCommerce Webhooks for Beginners
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.
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:
Access to a BigCommerce Store
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:
- A website that provides details about your agency.
- Intentions of releasing the apps you develop to the public.
- The ability to support the users of your app.
- Proof that you have extensive experience in app development.
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.
OAuth Client ID and Token
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.
Valid TLS/SSL Certificate
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:
- store_id: A numerical identifier for a BigCommerce store (this identifier is unique for each store).
- producer: The store that created the webhook. This element uses the format “stores/store_hash”.
- scope: The event that you’ve subscribed to with the webhook.
- data: A description of the subscribed event (remember that only minimal details will be included).
- hash: The payload data encoded in JSON and encrypted with SHA-1.
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:
X-Auth-Client: (your OAuth client id)
X-Auth-Token: (your OAuth token)
A webhook response contains the following elements:
- id: A unique read-only value that identifies the webhook (type: integer).
- client_id: The OAuth client ID that’s used to identify your application (type: string).
- store_hash: The hash value that’s used to identify the BigCommerce store (type: string).
- scope: Again, the event that you’ve subscribed to with the webhook (type: string).
- destination: The callback’s URI, which is the endpoint on your server that must be configured to receive webhook payloads (type: string).
- headers: The name-value pairs in the HTTP header of POST requests to your callback URI (type: string).
- is_active: Whether the webhook is active or inactive. New webhooks are set as inactive by default (type: boolean).
- created_at: When the webhook was created (type: date-time Unix Epoch).
- Updated_at: When the webhook was last updated (type: date-time Unix Epoch).
Callback Retry Process
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):
- 60 seconds after the initial three-minute blacklist
- 180 seconds after the first retry
- 180 seconds after the second retry
- 300 seconds after the third retry
- 600 seconds after the fourth retry
- 900 seconds after the fifth retry
- 1,800 seconds after the sixth retry
- 3,600 seconds after the seventh retry
- 7,200 seconds after the eighth retry
- 21,600 seconds after the ninth retry
- 50,400 seconds after the tenth retry
- 86,400 seconds (24 hours) after the eleventh retry
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.
BigCommerce Webhook Events
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:
- store/order/* - Subscribe to all order events.
- store/order/created - A new order is created.
- store/order/updated - An existing order is updated (a coupon is added, the shipping address is changed, etc.).
- store/order/archived - An order is archived.
- store/order/statusUpdated - An order’s status is updated (upgraded from “Awaiting Payment” to “Shipped”, “Shipped” to “Completed”, etc.).
- store/order/message/created - An order message is created.
Product-related events that you can subscribe to include:
- store/product/* - Subscribe to all product events.
- store/product/deleted - An existing product is deleted.
- store/product/created - A new product is created.
- store/product/updated - The details of an existing product are changed (category, inventory, etc.).
- store/product/inventory/updated - A product’s inventory is changed.
- store/product/inventory/order/updated - A product’s inventory decreases due to an order.
Category-related events that you can subscribe to include:
- store/category/* - Subscribe to all category events.
- store/category/created - A new category is created.
- store/category/updated - An existing category is updated (new title, edited description, etc.).
- store/category/deleted - An existing category is deleted.
SKU-related events that you can subscribe to include:
- store/sku/* - Subscribe to all SKU events.
- store/sku/created - A new SKU is created.
- store/sku/updated - An existing SKU is updated.
- store/sku/deleted - An existing SKU is deleted.
- store/sku/inventory/updated - The inventory of an SKU is updated.
- store/sku/inventory/order/updated - An order is placed, or an order is refunded and the item is returned to stock.
Customer-related events that you can subscribe to include:
- store/customer/* - Subscribe to all customer events.
- store/customer/created - A new customer is created.
- store/customer/updated - A customer’s information is changed (customer address is not included in this event).
- store/customer/deleted - An existing customer is deleted.
- store/customer/address/created - A new customer address is added.
- store/customer/address/updated - An existing customer address is updated.
- store/customer/address/deleted - An existing customer address is deleted.
- store/customer/payment/instrument/default/updatedCustomer - A customer’s default payment method is changed.
Store-related events that you can subscribe to include:
- store/app/uninstalled - A store uninstalls from the platform.
- store/information/updated - A store changes its settings (store name, store phone number, store time zone, etc.).
Cart-related events that you can subscribe to include:
- store/cart/* - Subscribe to all cart events (this will automatically subscribe you to the store/cart/lineItem* event, too).
- store/cart/created - A new cart is created.
- store/cart/updated - Changes are made to an existing cart’s line items (a new item is added to the cart, the quantity of an item is adjusted, etc.). This event will also be triggered when a new cart is created, as new carts are technically empty by default and the first item added counts as a change to the cart. A customer logging into their account after creating a cart or entering their email in guest checkout will trigger this event as well.
- store/cart/deleted - An existing cart is deleted. This event will be triggered whether the cart is manually deleted with items still inside the cart or automatically deleted by the customer removing all items from the cart (the last item being removed will also trigger store/cart/updated).
- store/cart/couponApplied - A new couple code is applied to the cart.
- store/cart/abandoned - A cart is abandoned (carts are considered abandoned when they are not converted or modified in over one hour).
- store/cart/converted - A cart is converted into an order. This will delete the cart.
Cart Line Item
Cart line item-related events that you can subscribe to include:
- store/cart/lineItem/* - Subscribe to all cart line item events.
- store/cart/lineItem/created - A new item is added to the cart.
- store/cart/lineItem/updated - The quantity or options for an item is changed.
- store/cart/lineItem/deleted - An existing item is deleted from the cart.
Shipment-related events that you can subscribe to include:
- store/shipment/* - Subscribe to all shipment events.
- store/shipment/created - A new shipment is created.
- store/shipment/updated - An existing shipment is updated (address, contact info, etc.).
- store/shipment/deleted - An existing shipment is deleted.
Subscriber-related events that you can subscribe to include:
- store/subscriber/* - Subscribe to all subscriber events.
- store/subscriber/created - A new subscriber is created.
- store/subscriber/updated - An existing subscriber is updated.
- store/subscriber/deleted - An existing subscriber is deleted.
BigCommerce Webhook Testing
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.