--- title: Subscribe to a webhook topic description: Learn how to set up and configure a webhook subscription using the app configuration file and GCP PubSub. source_url: html: https://shopify.dev/docs/apps/build/webhooks/subscribe/get-started?framework=remix&deliveryMethod=eventBridge md: https://shopify.dev/docs/apps/build/webhooks/subscribe/get-started.md?framework=remix&deliveryMethod=eventBridge --- # 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. ## What you'll learn In this tutorial, you'll learn how to do the following tasks: * Use your [app configuration file](https://shopify.dev/docs/apps/tools/cli/configuration#webhooks) to set up a webhook subscription. * Use cloud-based delivery methods like [Google Cloud's Pub/Sub event bus](https://cloud.google.com/pubsub) to receive webhooks. * Test your subscription is configured correctly and you are receiving webhooks. Info Shopify recommends using [Google Pub/Sub](https://cloud.google.com/pubsub) as a cloud-based solution for delivering webhooks. You can also use [Amazon EventBridge](https://aws.amazon.com/eventbridge/). In instances where you want to hand-roll your own webhooks infrastructure, you may prefer your webhooks be delivered through [HTTPS](https://shopify.dev/docs/apps/webhooks/configuration/https). During development, you may choose to use your app's URL or external mock server sites like [webhook.site](https://webhook.site/) and [Beeceptor](https://beeceptor.com/). These are not recommended for production. ## Requirements [Use the latest version of Shopify CLI](https://shopify.dev/docs/api/shopify-cli) Ensure you have the [latest version of Shopify CLI](https://shopify.dev/docs/api/shopify-cli#upgrade) installed to configure app-specific webhook subscriptions. [Sign up for Amazon EventBridge](https://aws.amazon.com/eventbridge/) Sign up for Amazon EventBridge. [Development tools](https://shopify.dev/docs/apps/build/webhooks/subscribe/get-started) For development, you can use mock servers like [Hookdeck Console](https://console.hookdeck.com/) or [webhook.site](https://webhook.site/) can be used for development. ## Project EventBridge [View on GitHub](https://github.com/Shopify/shopify-app-template-react-router/blob/webhooks-subscribe-example-eventBridge/shopify.app.toml) ## Set your app up to receive webhooks from Amazon Event​Bridge ### Set up a connection between Amazon Event​Bridge and Shopify 1. In your Developer Dashboard, in the Settings page for your app, click **Create source** under the **Amazon EventBridge** section. 2. Paste your AWS account ID, and choose your AWS region. You need the AWS region when you [associate an event bus](#grant-shopify-access-to-publish-webhooks-to-your-amazon-eventbridge-event-bus) with the source. 3. Provide a unique event source name. Each event source requires a unique name. If you have multiple apps, then consider a name that matches your app. 4. Click **Create**. ### Grant Shopify access to publish webhooks to your Amazon Event​Bridge event bus Follow [AWS EventBridge Resources](https://aws.amazon.com/eventbridge/resources/) instructions to set up an event bus from a Partner's event source: 1. In the AWS console, under **EventBridge**, navigate to the [Partner event sources](https://console.aws.amazon.com/events/home#/partners) page. 2. In the **Region** drop-down list, select the AWS region that you chose when you set up your event source. These regions must match for the event bus to connect with the event source. 3. Click the Partner event source [that you created](#set-your-app-up-to-receive-webhooks-from-amazon-eventbridge), and make note the ARN found under **Partner event source ARN**. You need this address to [subscribe to a webhook](#configure-the-endpoint-where-you-will-receive-webhooks). 4. Select the option to associate the event source with an event bus. ### Create a rule to ensure the webhook is routed to the target you want it sent to A rule is Amazon Eventbridge’s way of ensuring the event is routed to the target you want it sent to Amazon EventBridge groups and sorts the events that your event source sends based on the rules that you define. After you set up your event source and associate it with an event bus, create a rule that tells AWS what to do with events it receives on the bus. To define multiple rules, repeat this step for each rule. Note As your app audience grows, your traffic can increase significantly. Consider using [AWS CloudWatch](https://docs.aws.amazon.com/eventbridge/latest/userguide/eventbridge-monitoring-cloudwatch-metrics.html) to monitor your EventBridge integration for usage patterns and errors. For example, you can [trigger an alert](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-troubleshooting.html#create-alarm-broken-event-rules) if an EventBridge rule is broken. 1. In the [AWS console navigation menu](https://console.aws.amazon.com/events/home#/events) navigate to rules. 2. Select your event bus. 3. **Create a rule** with a rule type of **Rule with an event pattern** and provide a name and a description. 4. When building the event pattern, select the following options: * **EventBridge** partners as the source * **Shopify** as the Partner * **All Events** as the event type You can also [define a custom event pattern](#optional:-define-a-custom-event-pattern) for your rule. 1. In the **Targets** section, choose an AWS target such as a Lambda function or an SQS queue. Events that are processed by this rule are sent to the function or queue that you select. ### Optional: Define a custom event pattern When you create a rule, you can process events separately depending on factors like which shop generated the event or which resource triggered the event. [Event patterns](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-event-patterns.html) in EventBridge rules have the same structure as the payloads that they match. Matching values are added to an array and compared using `OR`. You can also match by prefix using the **prefix** key. 1. Select **Custom pattern**. 2. Provide a custom pattern that matches the [structure of an Amazon EventBridge payload](https://docs.aws.amazon.com/eventbridge/latest/userguide/event-reference.html). ## Configure your webhook subscription ### Update your access scopes Some webhook topics require scopes in order to be used. Since we want to know about when a product has been updated, we need to include the `read_products` scope in the configuration file. * To determine which scopes are required for each topic, use the [Webhooks reference](https://shopify.dev/docs/api/webhooks). * The complete list of Shopify API access and approval scopes are listed [here](https://shopify.dev/docs/api/usage/access-scopes). Info Scopes that access private customer data, such as `read_orders`, require manual steps in your Partner Dashboard. Go to your app > **API 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 ```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://:" [[webhooks.subscriptions]] topics = ["orders/create"] uri = "/webhooks/app/orders-create" [[webhooks.subscriptions]] topics = ["orders/create"] uri = "arn:aws:events:::event-source/aws.partner/shopify.com//" ``` ### Select 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](https://shopify.dev/docs/apps/build/webhooks/use-newer-api-version) as needed. ## /shopify.app.toml ```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://:" [[webhooks.subscriptions]] topics = ["orders/create"] uri = "/webhooks/app/orders-create" [[webhooks.subscriptions]] topics = ["orders/create"] uri = "arn:aws:events:::event-source/aws.partner/shopify.com//" ``` ### Configure topics to subscribe to To determine which topic to subscribe to, use the [Webhooks reference](https://shopify.dev/docs/api/webhooks). In this example, your topic name will be in a list and formatted as: `topics = ["orders/create"]`. Your endpoint address should be your ARN. You can find details in your Amazon EventBridge console: **Partner Event Sources** > **Select your event source** > **Partner event source ARN**. ## /shopify.app.toml ```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://:" [[webhooks.subscriptions]] topics = ["orders/create"] uri = "/webhooks/app/orders-create" [[webhooks.subscriptions]] topics = ["orders/create"] uri = "arn:aws:events:::event-source/aws.partner/shopify.com//" ``` ## Process your webhooks Follow the [Amazon EventBridge docs](https://www.npmjs.com/package/@aws-sdk/client-eventbridge) to subscribe to event data and process events. ### Confirm 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. 1. Save your TOML file. 2. If `app dev` is running, the webhook subscription will be automatically created or updated. 3. The webhook subscription is now active in your development store. Info This step abstracts away calls to the [`webhookSubscriptionCreate`](https://shopify.dev/docs/api/admin-graphql/latest/mutations/webhookSubscriptionCreate) GraphQL mutation Learn more about [subscribing to webhook topics using the GraphQL Admin API](https://shopify.dev/docs/apps/build/webhooks/subscribe/subscribe-using-api). ## Test your subscription ### Use Cloudwatch to ensure you can see the webhooks coming through 1. Copy and paste your event bus URL (this is your ARN). 2. Navigate to CloudWatch > Live tail. 3. Select EventBridge. ### Manually trigger an event in your test shop Most webhook topics will fire immediately if you trigger the corresponding event your dev store. 1. Navigate to your test shop and create a new order. 2. The webhook payload should appear in your Cloudwatch Live tail 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](https://shopify.dev/docs/apps/build/privacy-law-compliance#customers-redact) * The [shop/redact topic](https://shopify.dev/docs/apps/build/privacy-law-compliance#shop-redact) ### Simulate 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`](https://shopify.dev/docs/api/shopify-cli/app/app-webhook-trigger) The address inputted for the `--address` flag should be your ARN. You can find details in your Amazon EventBridge console: **Partner Event Sources** > **Select your event source** > **Partner event source ARN**. This the same format as the URI you specified in your app configuration file. ## Deploy 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](https://shopify.dev/docs/apps/launch/deployment/app-versions). An app version is a snapshot of your app configuration and all extensions. 1. Navigate to your app directory. 2. Run the following command. Optionally, you can provide a name or message for the version using the `--version` and `--message` flags. ## Terminal ```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`](https://shopify.dev/docs/api/shopify-cli/app/app-release) command, or through the Dev Dashboard. ## /shopify.app.toml ```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://:" [[webhooks.subscriptions]] topics = ["orders/create"] uri = "/webhooks/app/orders-create" [[webhooks.subscriptions]] topics = ["orders/create"] uri = "arn:aws:events:::event-source/aws.partner/shopify.com//" ``` ## 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. ### Next steps [![](https://shopify.dev/images/icons/32/build.png)![](https://shopify.dev/images/icons/32/build-dark.png)](https://shopify.dev/docs/apps/deployment/web) [Deploy your app](https://shopify.dev/docs/apps/deployment/web) [Follow our guide to deploy your React Router app to a testing or production environment.](https://shopify.dev/docs/apps/deployment/web) [![](https://shopify.dev/images/icons/32/gear.png)![](https://shopify.dev/images/icons/32/gear-dark.png)](https://shopify.dev/docs/api/webhooks) [Explore the Shopify Webhooks reference](https://shopify.dev/docs/api/webhooks) [Explore the Webhooks reference to learn about the full list of topics Shopify has, required access and approval scopes, and sample payloads.](https://shopify.dev/docs/api/webhooks) [![](https://shopify.dev/images/icons/32/gear.png)![](https://shopify.dev/images/icons/32/gear-dark.png)](https://shopify.dev/docs/apps/build/webhooks/customize) [Learn about customizing your webhooks](https://shopify.dev/docs/apps/build/webhooks/customize) [Customize your webhooks experience by using filters or modifying the payload per webhook.](https://shopify.dev/docs/apps/build/webhooks/customize) [![](https://shopify.dev/images/icons/32/apps.png)![](https://shopify.dev/images/icons/32/apps-dark.png)](https://shopify.dev/docs/apps/distribution) [Select an app distribution method](https://shopify.dev/docs/apps/distribution) [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.](https://shopify.dev/docs/apps/distribution)