Subscribe to a webhook topic

Subscribe your app to Shopify webhook topics so that it will be alerted when an event occurs on a merchant store.

Suppose you are building a warranty pricing app that determines which warranty options a customer can add to their cart, based on the cost of an order.

When a customer is checking out, the total order cost is used to determine which warranty options a customer can select from.

In this tutorial, you'll subscribe your app to a webhook topic to be alerted whenever a new order is created.

Anchor to What you'll learnWhat you'll learn

In this tutorial, you'll learn how to do the following tasks:

Use your app configuration file to set up a webhook subscription.
Use cloud-based delivery methods like Google Cloud's Pub/Sub event bus to receive webhooks.
Test your subscription is configured correctly and you are receiving webhooks.

Info

Shopify recommends using Google Pub/Sub as a cloud-based solution for delivering webhooks. You can also use Amazon EventBridge.

In instances where you want to hand-roll your own webhooks infrastructure, you may prefer your webhooks be delivered through HTTPS.

During development, you may choose to use your app's URL or external mock server sites like webhook.site and Beeceptor. These are not recommended for production.

Requirements

Use the latest version of Shopify CLI

Ensure you have the latest version of Shopify CLI installed to configure app-specific webhook subscriptions.

Set up a Google Cloud console project

Set up your Google Cloud account to use Pub/Sub.

Development tools

For development, you can use mock servers like Hookdeck Console or webhook.site can be used for development.

Project

Delivery method:

View on GitHub

Anchor to Set your app up to receive webhooks from Google Pub/SubSet your app up to receive webhooks from Google Pub/Sub

To receive webhooks via a cloud-based event bus like Pub/Sub from Google Cloud, you must first set up a connection between your app and Pub/Sub.

Anchor to Grant Shopify access to publish webhooks to your Google Pub/Sub topicGrant Shopify access to publish webhooks to your Google Pub/Sub topic

Click on Topics in the left panel.
Click on the Create a topic button. Enter in a name, keep the remaining defaults and click on Create.
Next to the Google Pub/Sub topic you just created, click ⋮ and then click View permissions.
Click on ADD PRINCIPAL.
Paste delivery@shopify-pubsub-webhooks.iam.gserviceaccount.com (the Shopify service account address) into the New principals text box.
In the Role drop-down list, select Pub/Sub as the type, and specify the role as Pub/Sub Publisher.
Click Save.

Anchor to Configure your webhook subscriptionConfigure your webhook subscription

Anchor to Update your access scopesUpdate your access scopes

Some webhook topics require scopes in order to be used. Since we want to know about when an order has been created, we need to include the read_orders scope in the configuration file.

To determine which scopes are required for each topic, use the Webhooks reference.
The complete list of Shopify API access and approval scopes are listed here.

Info

Scopes that access private customer data, such as read_orders, require manual steps in your Partner Dashboard. Go to your app > API Access > Access requests > Protected customer data access, fill out only the first step, and then save. Reinstall your app in the Shopify admin to register the granted scope.

/shopify.app.toml

# This file stores configurations for your Shopify app.

name = "Example App"

client_id = "a61950a2cbd5f32876b0b55587ec7a27"

application_url = "https://www.app.example.com/"

embedded = true

handle = "example-app"

[access_scopes]

scopes = "write_products, read_orders"

[webhooks]

api_version = "2024-07"

# Handled by: /app/routes/webhooks.app.uninstalled.tsx

[[webhooks.subscriptions]]

uri = "/webhooks/app/uninstalled"

topics = ["app/uninstalled"]

# Handled by: /app/routes/webhooks.app.scopes_update.tsx

[[webhooks.subscriptions]]

topics = [ "app/scopes_update" ]

uri = "/webhooks/app/scopes_update"

# Webhooks can have filters

# Only receive webhooks for product updates with a product price >= 10.00

# See: https://shopify.dev/docs/apps/build/webhooks/customize/filters

# [[webhooks.subscriptions]]

# topics = ["products/update"]

# uri = "/webhooks/products/update"

# filter = "variants.price:>=10.00"

# Mandatory compliance topic for public apps only

# See: https://shopify.dev/docs/apps/build/privacy-law-compliance

# [[webhooks.subscriptions]]

# uri = "/webhooks/customers/data_request"

# compliance_topics = ["customers/data_request"]

# [[webhooks.subscriptions]]

# uri = "/webhooks/customers/redact"

# compliance_topics = ["customers/redact"]

# [[webhooks.subscriptions]]

# uri = "/webhooks/shop/redact"

# compliance_topics = ["shop/redact"]

[[webhooks.subscriptions]]

topics = ["orders/create"]

uri = "pubsub://<PROJECT-ID>:<PUBSUB-TOPIC-ID>"

[[webhooks.subscriptions]]

topics = ["orders/create"]

uri = "/webhooks/app/orders-create"

[[webhooks.subscriptions]]

topics = ["orders/create"]

uri = "arn:aws:events:<AWS-REGION>::event-source/aws.partner/shopify.com/<APP-ID>/<EVENT-SOURCE-NAME>"

Anchor to Select the API versionSelect the API version

The API version impacts which topics are available to subscribe to. The React Router template defaults to the latest version in your app configuration file. However, you can update the API version as needed.

/shopify.app.toml

# This file stores configurations for your Shopify app.

name = "Example App"

client_id = "a61950a2cbd5f32876b0b55587ec7a27"

application_url = "https://www.app.example.com/"

embedded = true

handle = "example-app"

[access_scopes]

scopes = "write_products, read_orders"

[webhooks]

api_version = "2024-07"

# Handled by: /app/routes/webhooks.app.uninstalled.tsx

[[webhooks.subscriptions]]

uri = "/webhooks/app/uninstalled"

topics = ["app/uninstalled"]

# Handled by: /app/routes/webhooks.app.scopes_update.tsx

[[webhooks.subscriptions]]

topics = [ "app/scopes_update" ]

uri = "/webhooks/app/scopes_update"

# Webhooks can have filters

# Only receive webhooks for product updates with a product price >= 10.00

# See: https://shopify.dev/docs/apps/build/webhooks/customize/filters

# [[webhooks.subscriptions]]

# topics = ["products/update"]

# uri = "/webhooks/products/update"

# filter = "variants.price:>=10.00"

# Mandatory compliance topic for public apps only

# See: https://shopify.dev/docs/apps/build/privacy-law-compliance

# [[webhooks.subscriptions]]

# uri = "/webhooks/customers/data_request"

# compliance_topics = ["customers/data_request"]

# [[webhooks.subscriptions]]

# uri = "/webhooks/customers/redact"

# compliance_topics = ["customers/redact"]

# [[webhooks.subscriptions]]

# uri = "/webhooks/shop/redact"

# compliance_topics = ["shop/redact"]

[[webhooks.subscriptions]]

topics = ["orders/create"]

uri = "pubsub://<PROJECT-ID>:<PUBSUB-TOPIC-ID>"

[[webhooks.subscriptions]]

topics = ["orders/create"]

uri = "/webhooks/app/orders-create"

[[webhooks.subscriptions]]

topics = ["orders/create"]

uri = "arn:aws:events:<AWS-REGION>::event-source/aws.partner/shopify.com/<APP-ID>/<EVENT-SOURCE-NAME>"

Anchor to Configure topics to subscribe toConfigure topics to subscribe to

To determine which topic to subscribe to, use the Webhooks reference.

In this example, your topic name will be in a list and formatted as:

topics = ["orders/create"]

Your endpoint address should follow the following format:

pubsub://{project-id}:{topic-id}

/shopify.app.toml

# This file stores configurations for your Shopify app.

name = "Example App"

client_id = "a61950a2cbd5f32876b0b55587ec7a27"

application_url = "https://www.app.example.com/"

embedded = true

handle = "example-app"

[access_scopes]

scopes = "write_products, read_orders"

[webhooks]

api_version = "2024-07"

# Handled by: /app/routes/webhooks.app.uninstalled.tsx

[[webhooks.subscriptions]]

uri = "/webhooks/app/uninstalled"

topics = ["app/uninstalled"]

# Handled by: /app/routes/webhooks.app.scopes_update.tsx

[[webhooks.subscriptions]]

topics = [ "app/scopes_update" ]

uri = "/webhooks/app/scopes_update"

# Webhooks can have filters

# Only receive webhooks for product updates with a product price >= 10.00

# See: https://shopify.dev/docs/apps/build/webhooks/customize/filters

# [[webhooks.subscriptions]]

# topics = ["products/update"]

# uri = "/webhooks/products/update"

# filter = "variants.price:>=10.00"

# Mandatory compliance topic for public apps only

# See: https://shopify.dev/docs/apps/build/privacy-law-compliance

# [[webhooks.subscriptions]]

# uri = "/webhooks/customers/data_request"

# compliance_topics = ["customers/data_request"]

# [[webhooks.subscriptions]]

# uri = "/webhooks/customers/redact"

# compliance_topics = ["customers/redact"]

# [[webhooks.subscriptions]]

# uri = "/webhooks/shop/redact"

# compliance_topics = ["shop/redact"]

[[webhooks.subscriptions]]

topics = ["orders/create"]

uri = "pubsub://<PROJECT-ID>:<PUBSUB-TOPIC-ID>"

[[webhooks.subscriptions]]

topics = ["orders/create"]

uri = "/webhooks/app/orders-create"

[[webhooks.subscriptions]]

topics = ["orders/create"]

uri = "arn:aws:events:<AWS-REGION>::event-source/aws.partner/shopify.com/<APP-ID>/<EVENT-SOURCE-NAME>"

Anchor to Process your webhooksProcess your webhooks

Follow the Google PubSub docs to subscribe to event data and process events.

Anchor to Confirm the subscription has been added to this version of your appConfirm the subscription has been added to this version of your app

When working in development mode, webhook subscriptions are automatically updated when you save your TOML file.

Save your TOML file.
If app dev is running, the webhook subscription will be automatically created or updated.
The webhook subscription is now active in your development store.

Info

This step abstracts away calls to the webhookSubscriptionCreate GraphQL mutation

Learn more about subscribing to webhook topics using the GraphQL Admin API.

Anchor to Test your subscriptionTest your subscription

Anchor to Manually trigger an event in your test shopManually trigger an event in your test shop

Most webhook topics will fire immediately if you trigger the corresponding event your dev store.

Navigate to your test shop and create a new order.
The webhook payload should print to your Google Pub/Sub console.

Info

A small number of webhook topics will not fire immediately if you trigger an event in your test shop. They include:

The customers/redact topic
The shop/redact topic

Anchor to Simulate an event using the command lineSimulate an event using the command line

You can use the CLI to simulate specific events occurring on a shop. This lets you test your processing logic by sending a POST request to your endpoint with a synthetic webhook. Note that it does not test your subscription configuration!

shopify app webhook trigger

The address inputted for the --address flag should follow the following format:

pubsub://{project-id}:{topic-id}

Anchor to Deploy your appDeploy your app

When you're ready to release your webhook subscriptions to production:

When you're ready to release your changes to users, you can create and release an app version. An app version is a snapshot of your app configuration and all extensions.

Navigate to your app directory.
Run the following command.

Optionally, you can provide a name or message for the version using the --version and --message flags.

Terminal
shopify app deploy

Releasing an app version replaces the current active version that's served to stores that have your app installed. It might take several minutes for app users to be upgraded to the new version.

Tip

If you want to create a version, but avoid releasing it to users, then run the deploy command with a --no-release flag. You can release the unreleased app version using Shopify CLI's release command, or through the Dev Dashboard.

/shopify.app.toml

# This file stores configurations for your Shopify app.

name = "Example App"

client_id = "a61950a2cbd5f32876b0b55587ec7a27"

application_url = "https://www.app.example.com/"

embedded = true

handle = "example-app"

[access_scopes]

scopes = "write_products, read_orders"

[webhooks]

api_version = "2024-07"

# Handled by: /app/routes/webhooks.app.uninstalled.tsx

[[webhooks.subscriptions]]

uri = "/webhooks/app/uninstalled"

topics = ["app/uninstalled"]

# Handled by: /app/routes/webhooks.app.scopes_update.tsx

[[webhooks.subscriptions]]

topics = [ "app/scopes_update" ]

uri = "/webhooks/app/scopes_update"

# Webhooks can have filters

# Only receive webhooks for product updates with a product price >= 10.00

# See: https://shopify.dev/docs/apps/build/webhooks/customize/filters

# [[webhooks.subscriptions]]

# topics = ["products/update"]

# uri = "/webhooks/products/update"

# filter = "variants.price:>=10.00"

# Mandatory compliance topic for public apps only

# See: https://shopify.dev/docs/apps/build/privacy-law-compliance

# [[webhooks.subscriptions]]

# uri = "/webhooks/customers/data_request"

# compliance_topics = ["customers/data_request"]

# [[webhooks.subscriptions]]

# uri = "/webhooks/customers/redact"

# compliance_topics = ["customers/redact"]

# [[webhooks.subscriptions]]

# uri = "/webhooks/shop/redact"

# compliance_topics = ["shop/redact"]

[[webhooks.subscriptions]]

topics = ["orders/create"]

uri = "pubsub://<PROJECT-ID>:<PUBSUB-TOPIC-ID>"

[[webhooks.subscriptions]]

topics = ["orders/create"]

uri = "/webhooks/app/orders-create"

[[webhooks.subscriptions]]

topics = ["orders/create"]

uri = "arn:aws:events:<AWS-REGION>::event-source/aws.partner/shopify.com/<APP-ID>/<EVENT-SOURCE-NAME>"

Anchor to Tutorial Complete!Tutorial Complete!

Congratulations! You subscribed your app to a webhook topic using React Router, Google PubSub, and Shopify webhooks. Keep the momentum going with these related tutorials and resources.

Anchor to Next stepsNext steps

Deploy your app

Follow our guide to deploy your React Router app to a testing or production environment.

Explore the Shopify Webhooks reference

Explore the Webhooks reference to learn about the full list of topics Shopify has, required access and approval scopes, and sample payloads.

Learn about customizing your webhooks

Customize your webhooks experience by using filters or modifying the payload per webhook.

Select an app distribution method

Decide how you want to share your app with users. For example, you might make your app available in the Shopify App Store, and bill customers for usage.

Was this page helpful?