Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 28 ยท Projects

Project: Order Webhook Notifier App

Build a BigCommerce app that turns order webhooks into notifications: install flow, token storage, request verification, deduplication, retries and structured logs.

In this project you build a small but complete BigCommerce app: when a store receives an order, the app sends a notification such as "Order #101 from Ada: $45.90" to a chat channel or an email address. It is a good first app because it touches every important part: the install flow, secure token storage, a webhook receiver, verification, deduplication, retries and logging, with very little business logic on top.

A real app needs a registered app draft, a public HTTPS server and a store. None of that can run on this page, so the real-platform pieces are shown read-only and everything runnable is a simulation in Node.js: a fake platform that sends the install callback and the webhooks, and your app code reacting to them. Where the simulation differs from the real platform, we say so. The building blocks come from App Types and the OAuth Flow, Building an App Backend and Webhooks, with the general theory in Webhooks and Signatures.

What the app does

sequenceDiagram
    participant M as "Merchant"
    participant BC as "BigCommerce"
    participant App as "Notifier app"
    participant Chat as "Chat service"
    M->>BC: "Install app"
    BC->>App: "auth callback (code, scope, context)"
    App->>BC: "exchange code for access token"
    App->>BC: "register webhook store/order/created"
    BC->>App: "webhook: order id only"
    App->>BC: "GET order details"
    App->>Chat: "send notification"
    M->>BC: "Uninstall app"
    BC->>App: "uninstall callback"
    App->>App: "delete the store's token and data"

The full life of the app, from install to uninstall.

The scope list is small: the app needs read-only access to orders, both to fetch the details for the message and to be allowed to subscribe to order events. It has no reason to write anything. Always request the minimum, as explained in API Accounts, Tokens and Scopes.

Step 1: the install flow

When a merchant installs the app, the platform redirects to your auth callback with a temporary code, the granted scope and a context such as stores/abc123. Your server must:

  1. Verify that the request is the one you started (for apps that begin elsewhere, check state; for installs from the control panel, the platform initiates it).
  2. Exchange the code for an access token by calling the platform's token endpoint with your client ID and client secret.
  3. Store the token encrypted, keyed by the store hash taken from context.
  4. Register the webhook for store/order/created, pointing at your receiver URL, with a secret value in a custom header.
  5. Show the merchant a success page.

The exchange request is read-only here:

HTTP
POST https://login.bigcommerce.com/oauth2/token
Content-Type: application/x-www-form-urlencoded

client_id={client_id}&client_secret={client_secret}&code={code}&scope={scope}&grant_type=authorization_code&redirect_uri={callback_url}&context={context}

And the webhook registration (read-only):

JSON
POST /stores/{store_hash}/v3/hooks
{
  "scope": "store/order/created",
  "destination": "https://notifier.example.com/webhooks/bigcommerce",
  "is_active": true,
  "headers": { "X-Notifier-Secret": "{random secret for this store}" }
}

In the simulation below, a fake platform plays the part of both the login service and the API. The token store is a Map, and "encryption" is only simulated with a base64 wrapper to mark where real encryption (a key from a secret manager) belongs. Base64 is not encryption; this is a placeholder for the lesson.

Node.js Simulate install, token storage and uninstall

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 install stores one record and registers one hook; replaying the one-time code fails; the uninstall callback removes everything for that store. Removing data on uninstall is both a courtesy and, depending on where your merchants are, often a legal duty (see Privacy and Compliance).

Step 2: the receiver

The webhook payload does not contain the order, only a pointer to it. A typical payload has the scope (store/order/created), the store ID, the type and ID of the changed object, a hash and a timestamp. That is a design choice that keeps payloads small and avoids leaking data through a misrouted request. Your handler therefore has to fetch the order with the stored token.

The receiver should do its job in a strict order:

  1. Authenticate the request. Confirm it came from the platform. The platform lets you attach custom headers to a webhook; a secret you generate per store and check on arrival is the simplest proof. Compare secrets in constant time. Where a provider signs the body with an HMAC, you verify the signature over the exact raw bytes instead; the stand-in below uses an HMAC so you can practice the technique, but for BigCommerce follow the current documentation for what is available.
  2. Look up the store by the store ID in the payload. Unknown store: reject.
  3. Deduplicate. Deliveries can repeat. Keep the hash (or scope plus ID) of processed events in a store with an expiry.
  4. Acknowledge fast. Return a success status quickly; do slow work after.
  5. Fetch and notify, with retries for transient failures.
  6. Log one structured line per decision, without secrets or customer details beyond what you need.

An important subtlety: record an event as processed only after the work succeeded, or make the notification step itself idempotent. Otherwise a crash between "mark" and "send" loses a notification, and the opposite order may send twice. For a notification, an occasional duplicate is usually better than a miss, but pick the behavior on purpose (Idempotency).

Step 3: the whole pipeline, simulated

The second simulation sends five deliveries into the receiver: a good one, a duplicate of it, a forged one with a wrong signature, one for an order the API cannot find, and one where the chat service fails once before working. Time is not real: retries are recorded rather than waited for. The "platform" signs with HMAC-SHA256 over the raw body, a stand-in for whichever authenticity check your store uses.

Node.js Receiver with verification, dedupe, retry and logs

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.

Read the results line by line. The duplicate is acknowledged but sends nothing, so a retry by the platform cannot cause a second message. The forged request is refused with 401 before anything is parsed or looked up. The missing order gets a 200 because redelivery would never help, and a 500 would only make the platform retry and eventually deactivate the hook. The flaky chat service fails once, is retried within the same delivery and succeeds, so the last event is notified.

If it had failed all three times, the receiver would answer 500 and leave the event unmarked, relying on the platform to deliver again later. Whether to retry inside the request, or to enqueue a job and answer 200 immediately, depends on how long the notification can take; a queue is the sturdier design, and the one to use once the app has real traffic.

Production checklist

Before this app ships to real stores:

  • HTTPS everywhere, and callback URLs registered exactly in the app settings.
  • Encrypt tokens at rest, with a key outside the database; use a real random generator for secrets.
  • Rate-limit and size-limit the webhook endpoint, and parse only after verification.
  • Persist the dedupe record in a database or cache with expiry rather than in memory, because the process restarts and runs in many copies.
  • Add a queue between receiving and notifying.
  • Handle uninstalls and also stores that stop responding; the platform may deactivate a failing webhook, so provide a way to re-register it.
  • Write tests, as in Testing Apps and Themes, and run the launch checklist from Performance, Security and Launch.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why does the receiver fetch the order from the API instead of reading it from the webhook payload?

    Payloads point to the resource by ID. Fetching it gives you current data and keeps sensitive details out of webhook traffic.
  2. 2. Why is the one-time authorization code deleted after the first exchange?

    Authorization codes must be single-use. A replay is rejected, which limits the damage of a leaked code.
  3. 3. The chat service is down for a whole delivery. What should the receiver return, and why?

    A failure we want retried should not be acknowledged or marked as processed. A 200 would lose the notification.
  4. 4. Why return 200 for an event about an order that does not exist?

    Retry only what can succeed later. Log the problem and acknowledge so the platform does not keep redelivering.
  5. 5. What happens to the store's data when the uninstall callback arrives?

    Your app owns the data it stored. Delete it on uninstall, as promised in your listing and often required by privacy rules.

Summary

  • The notifier covers a full app lifecycle: install, token storage, webhook registration, receiving, uninstall.
  • Exchange the one-time code for a token, store it protected per store hash and request minimal scopes.
  • Webhook payloads identify the object; fetch details with the stored token.
  • Authenticate every delivery before parsing it, compare secrets in constant time and deduplicate by event hash.
  • Mark events processed only after success; return an error status only for failures that a retry can fix.
  • Log structured decisions without secrets, and persist dedupe data and use a queue in production.

Next: Project: A Custom Theme Section