Skip to content
Tutorials Center
My learning

Topics

Lesson 47 of 61 ยท Apps, Integrations and Extensibility

Webhooks and Orders for Theme Developers

What a theme developer needs to know about Shopify webhooks, order notification templates and the order lifecycle, with a runnable signature check and email stand-in.

A theme controls how a store looks. Orders, payments and fulfillment are handled by other parts of Shopify, and sooner or later a client will ask a question that crosses that line: "Can the order email use our brand colors?", "Our warehouse system needs to know when an order is paid", "Why can't you add a banner to the thank-you page?" To answer well, you need to know what a theme can touch, what it cannot, and how apps hear about orders through webhooks.

This lesson is the theme developer's view. It does not teach how to build a webhook receiver in full, because that is a back-end topic with its own track: the general ideas live in Webhooks and Signatures, The Order Lifecycle and Idempotency. Here you learn the Shopify-specific parts, and you run two stand-ins: one that verifies a webhook signature and one that renders an order email from a template.

Shopify's own code, admin screens and real webhook deliveries cannot run on this site. The Shopify snippets are read-only. The runnable examples are stand-ins written in JavaScript, and each one says what is real and what is imitation.

What a theme can and cannot do with orders

A theme only renders storefront pages. After the shopper presses the checkout button, the pages are no longer yours.

Stage Who owns it Can the theme change it?
Browsing, product, collection and cart pages Your theme Yes
Checkout, thank-you and order status pages Shopify's checkout, customized with checkout extensibility Not with theme files
Customer account (order history, addresses) Theme templates for classic accounts, or Shopify's hosted new customer accounts Only for classic account templates; see Customer Accounts
Order emails and SMS Notification templates in the admin Yes, but they are edited in the admin, not in the theme
Reacting to an order in another system Apps and webhooks No: a theme cannot receive a webhook

The old checkout.liquid file and the additional-scripts box are not how you customize checkout any more. Checkout appearance comes from the checkout branding settings and from checkout extensions built as apps. If a client wants a custom element on the thank-you page, the answer is "an app or extension", not a theme edit. The rules about what happens in checkout (taxes, shipping rates, discounts) are explained in Checkout Flow and in Cart, Discounts and the Path to Checkout.

flowchart LR
    T["Theme<br/>(browse, cart)"] --> C["Shopify Checkout<br/>(branding + extensions)"]
    C --> O["Order created"]
    O --> N["Notification templates<br/>(emails, SMS)"]
    O --> W["Webhooks<br/>(orders/create, orders/paid)"]
    W --> A["Apps and back-end systems"]

Your theme ends at the checkout button; notifications and webhooks start when the order exists.

Webhooks in one page

A webhook is a message Shopify sends to a URL when something happens in the store. Instead of an app asking "any new orders?" every minute, Shopify tells the app the moment an order is created. Each message has a topic that names the event. Common ones for orders are orders/create, orders/paid, orders/fulfilled and orders/cancelled. Products, customers, inventory and even themes have topics too (for example themes/publish, sent when a store publishes a different theme).

A delivery is an HTTP POST with a JSON body and a set of headers. The ones worth knowing:

  • X-Shopify-Topic: the event, such as orders/paid.
  • X-Shopify-Shop-Domain: which store sent it.
  • X-Shopify-Hmac-Sha256: a signature that proves the message came from Shopify.
  • X-Shopify-Webhook-Id: an identifier you can use to detect a delivery you already handled.
  • X-Shopify-API-Version: the API version the payload shape follows.

Three rules keep a receiver correct, and they match the general lessons linked above:

  1. Verify the signature before you trust anything. Without it, anyone who finds the URL can post fake "paid" orders.
  2. Answer quickly with a success status, and do slow work afterwards in a queue. Shopify retries deliveries that fail or time out.
  3. Be idempotent. Retries and occasional duplicates happen, so handling the same event twice must not ship two parcels. A stored webhook ID is the usual guard.

Where does a theme developer meet this? Usually in two situations: an agency needs to wire a theme-related event (like a theme publish) to a chat message or a deploy script, or a client's app needs order data and you must explain why it is not available in Liquid on the storefront. Knowing the vocabulary lets you route the request correctly.

Here is how a Shopify-style signature check works. The signature is an HMAC-SHA256 of the raw request body, encoded in base64, made with the app's client secret. This stand-in uses a made-up secret and signs its own message to show the logic. The signing and the comparison are real cryptography, but the delivery is imitation.

Node.js Verify a webhook signature

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.

Notice the third line: simply re-formatting the JSON changes the bytes, so the signature fails. That is why real receivers must hash the raw bytes they received, before any JSON parsing. The comparison uses timingSafeEqual so an attacker cannot learn the correct signature one character at a time by measuring response times.

In a real Shopify app you would not hand-write all of this. The official app libraries verify the signature and register topics for you. The read-only snippet below shows what a webhook subscription looks like in an app's configuration file (shopify.app.toml), so you recognize it when a developer shows it to you:

TOML
# Read-only: part of an app's configuration.
[webhooks]
api_version = "2026-07"

  [[webhooks.subscriptions]]
  topics = ["orders/paid"]
  uri = "/webhooks/orders-paid"

Notification templates: the part you can design

When an order is placed, Shopify sends emails such as the order confirmation, shipping confirmation, and cancellation notice. These are notification templates and you find them in the admin under Settings, Notifications. They are written in HTML and Liquid, just like a theme, but they differ in important ways:

  • They are not part of the theme. Switching or updating a theme does not change them, and you cannot edit them with the Shopify CLI theme commands.
  • They have their own objects. Instead of product and collection you work with order data such as the order name, the line items, the shipping address and the shop. Shopify documents the available variables for each template in the admin, so check there rather than assuming a theme object exists.
  • They render in email clients, which support a small subset of modern CSS. Expect table-based layout, inline styles and limited fonts.
  • Everything shoppers typed is still untrusted. A gift note, a name or a line-item property can contain HTML, so the escape filter applies here too (Security in Themes).

A good habit is to treat a notification like a small template with a strict contract: you receive an order and the shop, you print text and totals. The stand-in below imitates that with a tiny Liquid-style engine. It supports {{ output }}, filters (money, upcase, times, escape), for and if. It is not Shopify's real Liquid, and the objects here are simplified: in a real notification the line item variables have different names.

JS Render an order email from a template

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

No output.

Look at the last line of the output. The gift note contained <b>, and the escape filter turned it into harmless text. Remove | escape from the template and rerun to see what a mail client would be handed. Also notice that money is stored as integer cents and divided only when displayed, a habit that avoids rounding errors and is covered in the e-commerce lessons.

Practical advice for notification work

  • Send a test. The admin can send a test version of a notification to your address. Use real-looking orders, including one with a long product name, a discount and a line-item property.
  • Match the brand, not the theme. Reuse colors and the logo, but accept that fonts and layouts will be simpler than the storefront.
  • Keep Liquid small. Complicated logic in an email is hard to debug, and a rendering error can send a broken email to a customer.
  • Version the text. Notification templates are not in your theme repository, so copy changes into your project's documentation, or you will not know what was edited later.

What to tell a client

When a request touches orders, a short mental routing table saves hours:

  • "Change the colors or wording of the order email" is a notification template, edited in the admin.
  • "Add a section to the thank-you page" is a checkout extension (an app), not a theme change.
  • "Send new orders to our ERP" is a webhook subscription handled by an app or a back-end service, with signature verification and idempotency.
  • "Show past orders in the account area" is a customer account template, if the store uses classic accounts.
  • "Show the order total in the cart" is a theme job, covered in the cart lessons.

Knowing this saves you from promising a theme feature that Shopify does not allow, and lets you ask the right questions when a client's wishes cross into app territory. The next two lessons stay in that territory: the extension architecture for apps and the responsible loading of third-party code.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A client wants a custom message block on the thank-you page. Which statement is correct?

    Checkout and the thank-you page are customized with checkout branding and checkout extensions, not through theme files.
  2. 2. Why must a webhook receiver compute the HMAC over the raw request body?

    The signature covers the exact bytes Shopify sent. Even harmless re-formatting produces a different hash, as the stand-in showed.
  3. 3. Where are order confirmation emails edited?

    Notification templates live in the store admin and are independent of the active theme.
  4. 4. Shopify retries a webhook delivery after a timeout. What design rule protects you from processing the order twice?

    Retries and duplicates are normal. An idempotent handler recognizes an event it already handled and does nothing the second time.
  5. 5. A gift note from a shopper is printed in an order email template. What should you do?

    Shopper-typed text can contain HTML. Escape it in emails just as you would on a storefront page.

Summary

  • A theme ends at the checkout button; checkout, the thank-you page and order status are customized with checkout settings and extensions, not theme files.
  • Webhooks are signed messages Shopify sends to an app when an event (a topic such as orders/paid) happens; a theme cannot receive them.
  • A safe receiver verifies the HMAC over the raw body, answers fast, and handles duplicates idempotently.
  • Order emails are notification templates edited in the admin, in Liquid with their own objects and limited email CSS, and they still need escape for shopper text.
  • Route client requests to the right owner: theme, notification template, checkout extension, or app webhook.

Next: Theme App Extensions and Third-Party Scripts