Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 55 ยท Webhooks

Webhooks in Shopify

Learn how Shopify webhooks work: topics, TOML and API subscriptions, HTTPS, EventBridge and Pub/Sub delivery, request headers, and a runnable webhook dispatcher stand-in.

Polling an API to ask "has anything changed?" wastes requests and is always a little late. A webhook reverses the direction: when something happens in a shop (an order is created, a product is edited, your app is uninstalled), Shopify sends an HTTP request to a URL you registered. Your app reacts the moment it matters, and you spend your API rate limit on real work rather than on checking.

This lesson covers the Shopify-specific side: what a topic is, the two ways to create a subscription, the three delivery methods, and the headers on each request. The general theory (why signatures exist, at-least-once delivery) is in Webhooks and Signatures; the next two lessons cover verifying signatures and building reliable handlers. Configuration snippets target API version 2026-07 and are read-only, since they need a real app; the runnable part is a small dispatcher that routes incoming deliveries to handlers.

Topics

A topic names an event. Topics are written as resource/event and mirror the Admin API's objects. Some commonly used ones:

Topic Fires when
orders/create, orders/paid, orders/updated, orders/cancelled The order lifecycle (Order Lifecycle) progresses
products/create, products/update, products/delete Catalog changes
inventory_levels/update Stock at a location changes
customers/create, customers/update Customer records change (protected data rules apply)
app/uninstalled A merchant removes your app
app/scopes_update The app's granted scopes change

The exact list grows with each API version and is available in the reference for your version. Two practical points. First, a topic is only delivered if your app has the access scope to read that resource: orders need the order scopes, products need product scopes (Managed Installation and Access Scopes). Second, subscribe only to topics you handle. Every extra subscription is traffic you must accept, verify and discard.

Three compliance topics are special and every public app must handle them: customers/data_request, customers/redact and shop/redact. They are covered in Privacy, GDPR and Mandatory Webhooks.

Two ways to subscribe

App-specific subscriptions in shopify.app.toml

For most apps, declare subscriptions in the config file (App Configuration with shopify.app.toml). They belong to the app and are applied to every shop that installs it when you deploy a new app version. You do not register them per shop.

TOML
# read-only: shopify.app.toml
[webhooks]
api_version = "2026-07"

  [[webhooks.subscriptions]]
  topics = ["app/uninstalled"]
  uri = "/webhooks/app/uninstalled"

  [[webhooks.subscriptions]]
  topics = ["orders/create", "orders/updated"]
  uri = "/webhooks/orders"

  [[webhooks.subscriptions]]
  compliance_topics = ["customers/data_request", "customers/redact", "shop/redact"]
  uri = "/webhooks/compliance"

A relative uri is resolved against your application_url. Subscriptions in TOML can also filter events and trim the payload; for example a filter such as filter = "variants.price:>=10" limits deliveries to matching resources, and include_fields lists the fields you want. Filtering reduces both traffic and the personal data you receive, which is good privacy practice. Check the current documentation for the filter syntax of each topic before relying on it.

Subscriptions through the API

The alternative is to create subscriptions at runtime with the webhookSubscriptionCreate mutation. This gives shop-specific subscriptions, useful when only some merchants need a topic or when you cannot use TOML. The mutation takes a topic and a subscription input with the delivery destination.

GRAPHQL
# read-only
mutation Subscribe($topic: WebhookSubscriptionTopic!, $url: URL!) {
  webhookSubscriptionCreate(
    topic: $topic
    webhookSubscription: { uri: $url, format: JSON }
  ) {
    webhookSubscription { id topic }
    userErrors { field message }
  }
}

As with every mutation, read userErrors (Mutations and userErrors). Mixing both styles for the same topic can deliver duplicates, so pick one per topic. The rule of thumb: TOML for what every install needs, the API for per-shop exceptions.

Delivery methods

Shopify can deliver to three kinds of destination, chosen by the form of the uri:

Method uri looks like Use it when
HTTPS https://app.example.com/webhooks or a relative path The usual choice: you run a web server
Amazon EventBridge an event source ARN You live in AWS and want events on an event bus
Google Cloud Pub/Sub pubsub://project-id:topic-id You live in Google Cloud and want a topic

HTTPS needs a signature check on every request, as in Verifying Webhook Signatures. EventBridge and Pub/Sub put events straight into your cloud's queue infrastructure, so there is no public endpoint to defend and you get the cloud's own retry and buffering. The setup details (permissions, event sources) differ by provider, so follow the current guide for your cloud.

What a delivery looks like

An HTTPS delivery is a POST with a JSON body and a set of headers that tell you what you received:

HTTP
POST /webhooks/orders HTTP/1.1
Content-Type: application/json
X-Shopify-Topic: orders/create
X-Shopify-Shop-Domain: your-shop.myshopify.com
X-Shopify-API-Version: 2026-07
X-Shopify-Hmac-Sha256: <base64 signature of the raw body>
X-Shopify-Webhook-Id: <unique per delivery attempt chain>
X-Shopify-Event-Id: <identifies the underlying event>
X-Shopify-Triggered-At: 2026-07-04T10:15:00.000Z
  • X-Shopify-Topic and X-Shopify-Shop-Domain route the work: which event, which merchant. Multi-tenant apps key all data by the shop domain.
  • X-Shopify-Hmac-Sha256 proves the request came from Shopify.
  • X-Shopify-API-Version tells you the payload's shape; payloads are versioned like the API.
  • X-Shopify-Webhook-Id and X-Shopify-Event-Id are your keys for de-duplication (Reliable Webhook Handlers).

The payload is a snapshot at the time of the event, not necessarily the latest state. If you need current data, use the ID in the payload to query the API.

flowchart LR
    SH["Shopify event<br/>(order created)"] --> T{"Subscription<br/>for topic?"}
    T -->|"HTTPS"| H["POST to your endpoint"]
    T -->|"EventBridge"| EB["AWS event bus"]
    T -->|"Pub/Sub"| PS["Google topic"]
    H --> V["Verify HMAC"] --> R["Route by topic"]

One event, three possible destinations; HTTPS needs signature verification.

A dispatcher stand-in

Real apps route each delivery to a handler by topic. The stand-in below implements the routing, header checks and response codes (no real HMAC here; that is the next lesson). It shows two things worth copying: handlers are registered in a table so adding a topic is one line, and unknown topics get a clear response instead of an exception.

JS Route webhook deliveries by topic

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

No output.

The second example compares the two subscription styles by expanding a TOML-like config into the list of topic-to-URL routes a shop would end up with. It is a plain object, not a TOML parser, but it makes the "relative uri resolves against application_url" rule concrete.

JS Expand subscriptions into routes

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

No output.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is a webhook topic?

    Topics identify events in resource/event form. A subscription says which topics are delivered where.
  2. 2. Where do you declare subscriptions that every installation of your app needs?

    App-specific subscriptions in TOML are shared by all installs. The webhookSubscriptionCreate mutation is for shop-specific exceptions.
  3. 3. Which header tells you which merchant a delivery belongs to?

    The shop domain header identifies the merchant; the HMAC header carries the signature and the API version header describes the payload shape.
  4. 4. When is Pub/Sub or EventBridge delivery a good fit?

    They feed events straight into your cloud's messaging services, with its buffering and retry features, and avoid exposing a public webhook endpoint.
  5. 5. Why should you subscribe only to topics you handle?

    Extra subscriptions add load and privacy exposure for no benefit. Filters and field lists reduce both further.

Summary

  • A webhook is Shopify calling you when an event (topic) happens; it needs the matching access scope.
  • Declare app-wide subscriptions in shopify.app.toml and use webhookSubscriptionCreate for per-shop needs; do not duplicate one topic across both.
  • Deliveries go over HTTPS, Amazon EventBridge or Google Cloud Pub/Sub; HTTPS requests must be verified.
  • Headers carry the topic, shop domain, API version, HMAC and ids you need for routing and de-duplication.

Next: Verifying Webhook Signatures.