Subscribe to a topic using GraphQL Admin API

To configure shop-specific subscriptions, use the GraphQL Admin API. Shopify recommends using your app configuration file in most instances, and when when configuring app-specific subscriptions. Refer to the tutorial for setting up a subscription to learn how.

Requirements

Anchor link to section titled "Requirements"

You have created an app either using the Shopify CLI and the Remix template, or if you are creating a custom app in the Shopify Admin.
You have Google Cloud Pub/Sub or Amazon EventBridge set up, or a server available for HTTPS delivery. To learn more about setting these event buses up, find the first steps in the tutorial for setting up a webhook subscription.

What you'll learn

Anchor link to section titled "What you'll learn"

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

Use the GraphQL Admin API to create a webhook subscription.
Test your subscription is configured correctly and you are receiving webhooks.

Step 1: Create a webhook subscription

Anchor link to section titled "Step 1: Create a webhook subscription"

Recommended: Use the Shopify CLI and Remix template

Anchor link to section titled "Recommended: Use the Shopify CLI and Remix template"

Shopify recommends that you use the Shopify CLI and Remix template when subscribing to webhooks using the GraphQL Admin API. The template abstracts away the actual GraphQL mutation you would otherwise have to write.

You might want to create a subscription to the ORDERS_CREATE topic using the GraphQL Admin API. Specify the topic name using GraphQL's enum screaming case syntax, as well as the subscription endpoint you want to use to receive webhooks.

Add this information and the following code to your app in the app/shopify.server.ts file.

Developing with GraphQL mutations directly

Anchor link to section titled "Developing with GraphQL mutations directly"

For apps that are not using the Remix template, to create a new webhook subscription, you'll use the webhook subscription mutations found in our GraphQL Admin API reference.

You might want to create a subscription to the ORDERS_CREATE topic using the GraphQL Admin API. Specify the topic name using GraphQL's enum screaming case syntax, as well as the subscription endpoint you want to use to receive webhooks.

Add this information and the following code to your app, wherever you process your after-authentication hooks. This would be the equivalent to the app/shopify.server.ts file in the Remix template, because this is where the afterAuth code lives.
You might want to test out your code or example GraphQL queries before adding it to your app. In this case, you can use the GraphiQL interface by pressing g in the console where your app is running. You must include values for the variables in order to execute the mutations.

Request: POST /admin/api/2024-10/graphql.json

Step 2: Test your subscription is working

Anchor link to section titled "Step 2: Test your subscription is working"

You can use Shopify CLI's webhook trigger command to test webhook delivery. When using this command, note the difference in the URI that you should input for the --address flag:

For Google Pub/Sub, the address is:

{project-id}: The ID of your Google Cloud Platform project
{topic-id}: The ID of the topic that you set up in Google Cloud Pub/Sub

For Amazon EventBridge, the address is:

This is your ARN. You can find details in your Amazon EventBridge console: Partner Event Sources > Select your event source > Partner event source ARN.