Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 28 ยท Apps and OAuth

Webhooks

Register BigCommerce webhooks, read their payloads, authenticate them with custom headers, survive retries and deactivation, and write idempotent handlers.

Polling an API to ask "did anything change?" wastes requests and always lags behind. Webhooks reverse the direction: BigCommerce calls your server when something happens, such as an order being created or a product being updated. Almost every real app needs them, to keep a warehouse system in step, send a notification, or invalidate a cache.

The general theory of webhooks, signatures and reliable handling is covered in Webhooks and Signature Verification and Idempotency and Reliable Payments; read them if you have not, because this lesson applies those ideas to BigCommerce. Registering a webhook needs a live store, so those calls are read-only. The runnable stand-ins are Node.js programs: a receiver that authenticates and de-duplicates deliveries, and a delivery simulation with retries and deactivation. Their numbers and header names are our own, labelled where it matters.

Scopes and destinations

A webhook is a registration saying: "when an event with this scope happens, send an HTTP request to this destination." Scopes are named like paths, for example store/order/created, store/order/statusUpdated, store/product/updated or store/cart/abandoned. A wildcard such as store/order/* subscribes to a family of events. The full list is in the official reference, and your API account or app needs the matching scopes to register hooks.

You create a webhook with a POST to the V3 hooks endpoint of a store (read-only):

HTTP
POST /stores/{store_hash}/v3/hooks HTTP/1.1
Host: api.bigcommerce.com
X-Auth-Token: <access token>
Content-Type: application/json

{
  "scope": "store/order/created",
  "destination": "https://app.example.com/webhooks/orders",
  "is_active": true,
  "headers": { "X-Hook-Secret": "<long random value>" }
}

The headers object is important: BigCommerce will send those custom headers with every delivery. That is your hook for authentication, covered below. The destination must be a public HTTPS URL. An app registers its hooks for each store at install time, using that store's token, and deletes them on uninstall (see Building an App Backend).

The payload is a pointer

A delivery is a small JSON POST. It tells you what happened and which resource, not the full resource. A representative shape (field list simplified; check the documentation for the current one):

JSON
{
  "scope": "store/order/created",
  "store_id": "1025646",
  "data": { "type": "order", "id": 250 },
  "hash": "352e4afc6dd3afe2cb9f3d3a3b9f2c9b8d1f0a11",
  "created_at": 1561482670,
  "producer": "stores/abc123"
}

Notice there is no customer name, no line items, no totals. To act on the event your handler calls the API with the stored token and fetches the order by data.id. This design has two benefits: payloads stay small and carry little personal data, and you always read the current state rather than a possibly stale snapshot. It also means a webhook is a nudge: your handler should be written as "something changed for order 250, go and look", which makes duplicates and reordering far less dangerous.

sequenceDiagram
    participant BC as BigCommerce
    participant H as Your webhook endpoint
    participant Q as Queue
    participant W as Worker
    BC->>H: POST scope, data.id (with custom header)
    H->>H: Check header, dedupe
    H-->>BC: 200 OK (fast)
    H->>Q: enqueue event
    Q->>W: process later
    W->>BC: GET /orders/250 with store token

Acknowledge quickly, then do the slow work from a queue.

Authenticating deliveries

Anyone who learns your webhook URL can send fake requests to it, so a handler must check that a delivery really came from the platform. With BigCommerce webhooks, the practical tool is the custom header you set at registration: a long random value that the platform sends and an attacker does not know. Compare it in constant time and reject anything else with a 401 or 403. Use a different secret per store or per hook if you can, so one leak does not expose all stores.

Do not confuse this with a payload signature. Many other platforms sign the body with an HMAC. If you want that style of protection (for example when events pass through your own gateway first), you compute it yourself over the raw body, and the stand-in below includes the check so you can see it. Whatever method you choose, also keep the endpoint on HTTPS and give it an unguessable path. Because the payload only points to a resource, even a forged event cannot inject data: your handler would just fetch the real order, which is a safe default.

Retries and deactivation

Your endpoint will sometimes be down or slow. If a delivery gets no success response, the platform retries it several times with growing delays over a period of many hours. If failures continue long enough, it marks the webhook inactive and stops sending until you re-activate it. The exact schedule is documented by the platform and can change, so build for the principle instead of the numbers:

  • Respond fast with a 2xx as soon as the event is safely recorded. Do heavy work after responding.
  • Expect duplicates. At-least-once delivery means the same event can arrive twice, for instance when your 200 was lost on the way back.
  • Do not rely on order. An "updated" event can arrive before a "created" one in rare cases, another reason to fetch current state.
  • Watch for deactivation. Periodically list your hooks and re-enable inactive ones, and alert when it happens. After an outage, run a reconciliation job (list recent orders and compare with what you processed) to catch events that were dropped for good.

Idempotent handlers

A handler is idempotent when processing the same event twice has the same effect as processing it once. Two techniques combine well:

  1. Dedupe by event identity. Build a key from the scope, the resource id and the payload hash (or created_at) and remember keys you have already handled. Confirm in a sandbox which fields change between genuine repeats and genuine new events for your scope.
  2. Make the effect itself idempotent. "Set status of order 250 in my system to what the API says" can be repeated safely; "send an email" cannot, unless you record that you sent it.

The first stand-in is a receiver that checks the custom header, optionally verifies an HMAC over the raw body, and ignores duplicates.

Node.js A webhook receiver: authenticate, dedupe, handle

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first delivery is processed, the repeat is acknowledged with 200 but ignored, and every unauthenticated or malformed request is refused with a status that tells the sender whether to retry. Note that a duplicate still gets 200: answering with an error would make the platform retry something you already handled.

Simulating retries and deactivation

The second stand-in is a delivery engine with a flaky receiver. It retries failed deliveries with growing delays, gives up after a number of attempts and deactivates the hook, like the real platform does (with its own, documented schedule; the schedule here is invented). It also shows the receiver staying correct despite a lost acknowledgment.

Node.js Retries, duplicates and deactivation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Event e1 succeeds on its third attempt. For e2 the work was done on the first attempt but the acknowledgment was lost, so the platform delivered it again; because the receiver is idempotent, the effect ran once. e3 never succeeded, so the hook ended up inactive. That last state is exactly why you monitor hooks and reconcile after outages. Next you move from server-side integrations to themes, starting with Stencil CLI and the Cornerstone Theme.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does a typical BigCommerce webhook payload contain?

    Payloads are pointers. You fetch the current resource, which keeps payloads small and avoids stale data.
  2. 2. How can you authenticate deliveries from the platform?

    Custom headers set at registration act as a shared secret. Reject deliveries that do not carry it.
  3. 3. A duplicate event arrives. What should your endpoint answer?

    An error would trigger more retries of work you have already done. Acknowledge it and skip the effect.
  4. 4. Why respond quickly and process from a queue?

    Acknowledge once the event is recorded, then work asynchronously so timeouts do not cause duplicate deliveries.
  5. 5. What should you do after a long outage of your endpoint?

    Retries stop eventually and hooks can be deactivated. Reconciliation catches events that were permanently missed.

Summary

  • A webhook registers a scope and a destination (plus optional custom headers) with the V3 hooks endpoint.
  • Payloads point at a resource; fetch its current state with the store token.
  • Authenticate with a secret custom header (and optionally your own HMAC), compared in constant time.
  • Expect retries, duplicates and reordering; respond fast with 2xx, de-duplicate and make effects idempotent.
  • Monitor for deactivated hooks and reconcile after outages.

Next: Stencil CLI and the Cornerstone Theme