What is a webhook?

When an app promises it "finds out instantly" what you change in your store, it is almost always talking about webhooks. A webhook is not an API you ask, or a piece of code installed in the theme: it is a notification the platform sends to another application when something happens, be it a new order or a changed price. It matters to you because those notifications are what decides whether your feed, your PIM or your marketing tool have the same price as your product page, and because, sometimes, the notifications do not arrive.

How it works

The application that wants to find out subscribes to a type of event and gives an address. When the event occurs, the platform sends it the data. Shopify explains it with orders: instead of querying the API over and over to see whether there are new orders, the app subscribes to the orders/create topic and Shopify sends it each order when it is created. Its webhooks deliver data in near real time, serve to stay in sync with the store or to trigger another action, and can go to a URL, to Google Pub/Sub or to Amazon EventBridge.⁠^{[1]Shopify Dev Docs. About webhooks}

In BigCommerce, a subscription is created with a POST request to /v3/hooks.⁠^{[2]BigCommerce Docs. Webhooks} For the catalog there are events for product created, updated and deleted, for inventory changes and for metafields on the product or its variants. The store/product/updated event fires when, among others, the price, dimensions, availability, description, name, SKU, visibility or shipping data change.⁠^{[3]BigCommerce Docs. Webhook events}

What arrives in the notification varies a lot from one platform to another. BigCommerce sends notifications that are lightweight on purpose: the one for an order status change carries only its identifier, and to see the order you have to request it from the API.⁠^{[2]BigCommerce Docs. Webhooks} The one for an updated product carries its identifier and the list of properties that changed.⁠^{[3]BigCommerce Docs. Webhook events}

Three operational details decide whether a webhook works in practice:

• The signature. Every Shopify delivery carries the X-Shopify-Hmac-Sha256 header, which serves to check that the notification comes from Shopify, and X-Shopify-Webhook-Id, to recognize repeated deliveries.⁠^{[1]Shopify Dev Docs. About webhooks}
• The response. Your server has to answer in under five seconds with a 200-series code for Shopify to count the delivery as good. If not, it retries up to eight times over four hours, and if the failures continue, it removes the subscription.⁠^{[4]Shopify Dev Docs. Troubleshooting webhooks} BigCommerce also expects a 200; it retries at increasingly long intervals and, after the last failure, deactivates the webhook and emails the subscribed app.⁠^{[2]BigCommerce Docs. Webhooks}
• The order. Shopify does not guarantee the order of notifications, either within the same topic or across different topics.⁠^{[1]Shopify Dev Docs. About webhooks}

Event versus periodic sync

The most important sentence in Shopify's documentation is a warning: a webhook does not always arrive, and an app should not depend only on receiving them. Its recommendation is to add reconciliation jobs that query the store every so often, filtering by the update date to request only what changed.⁠^{[1]Shopify Dev Docs. About webhooks} So the question is not webhook or periodic sync, but how they split the work:

With both, the notification gives the speed and the periodic pass fixes what the notification missed. Without the pass, every lost notification is a difference nobody sees, and those differences pile up until they become data drift.

In a store

This is the sample notification BigCommerce publishes for an updated product:⁠^{[3]BigCommerce Docs. Webhook events}

{
  "scope": "store/product/updated",
  "store_id": "1025646",
  "data": {
    "type": "product",
    "id": 205,
    "properties": ["warranty", "is_featured", "custom_fields"],
    "context": { "channel_id": 2, "locale": "fr" }
  },
  "hash": "a833a57fadd56a32dc752fb6ca0841dc9602a495",
  "created_at": 1561479233,
  "producer": "stores/{store_hash}"
}

It does not carry the new warranty, or the new custom fields: it carries product 205 and the names of what changed. The app that receives it has to request the product from the catalog API to learn the values.⁠^{[2]BigCommerce Docs. Webhooks}

Now a fictional example of what happens when it fails. A tripod store changes a model's price in its PIM, which writes it to BigCommerce. The app that generates the feed for a comparison site is subscribed to store/product/updated, but its server is down that afternoon. BigCommerce retries for hours and, after the last failure, deactivates the subscription and sends an email to the app's address.⁠^{[2]BigCommerce Docs. Webhooks} If nobody reads that email and the app has no periodic pass, the feed stays on the old price, and on every change that comes after it too, because no notification arrives anymore.

How to check it

1. Ask each app connected to your store for the list of events it is subscribed to and what it does with each. If it does not use webhooks, ask how often it queries the store.
2. Ask whether the app has a periodic reconciliation pass, and how often it runs. It is what Shopify recommends so you do not depend only on notifications.⁠^{[1]Shopify Dev Docs. About webhooks}
3. If the app is yours, check that it verifies the signature of each notification with the X-Shopify-Hmac-Sha256 header and discards repeats by X-Shopify-Webhook-Id.⁠^{[1]Shopify Dev Docs. About webhooks}
4. Measure how long your server takes to answer: above five seconds, Shopify counts the delivery as failed.⁠^{[4]Shopify Dev Docs. Troubleshooting webhooks}
5. In BigCommerce, watch the app's inbox: the deactivation email is the only warning that notifications stopped arriving.⁠^{[2]BigCommerce Docs. Webhooks}

Related concept: catalog API

The catalog API and the webhook are the two directions of the same conversation. With the API, your application asks and the platform answers; with the webhook, the platform notifies without anyone asking. Shopify presents the webhook precisely as the alternative to querying the API over and over.⁠^{[1]Shopify Dev Docs. About webhooks} In BigCommerce they work together by design: the notification says which product changed and the API says how it ended up.⁠^{[2]BigCommerce Docs. Webhooks} If what worries you is who wrote a field last, that is field overwrite, and if you want to be able to go back, content versioning.

To keep going, the publishing by platform reading path orders the rest of the terms.