Google Cloud Pub/Sub webhook delivery

Integrate your app with Google Cloud Pub/Sub consume events at your app's own pace and handle large volumes of webhook traffic without getting overwhelmed.

This tutorial shows you how to use Google Cloud Pub/Sub to manage webhook events for your app.

Requirements

Anchor link to section titled "Requirements"

You're familiar with how webhooks work.
You're familiar with the webhooks best practices.
You're authenticated with the GraphQL Admin API or REST Admin API.
You've created an app.
You've set up a Google Cloud Pub/Sub project.
You've created at least one topic in the project.
You're using API version 2021-07 or higher.

For more information on creating projects and topics, refer to Google's Pub/Sub quickstart guide.

Step 1: Retrieve your Shopify service account address

Anchor link to section titled "Step 1: Retrieve your Shopify service account address"

To integrate your app with Google Cloud Pub/Sub, you need to get the Shopify service account address from the Partner Dashboard. You'll add the address to a Google Cloud Pub/Sub topic.

Navigate to your app's settings page in the Partner Dashboard or Shopify admin:
1. In your Partner Dashboard, go to Apps.
2. Click the name of your app.
3. Click App setup.
1. In your Shopify admin, go to Settings.
2. Click Apps and sales channels.
3. Click Develop apps for your store.
4. Click the name of your app.
5. Click Configuration.
6. Next to Admin API integration, click Configure.
Under Google Cloud Platform - Pub/Sub, copy the Shopify service account address.

Step 2: Add the service account address to Google Cloud Pub/Sub

Anchor link to section titled "Step 2: Add the service account address to Google Cloud Pub/Sub"

In the Google Cloud Console, go to Pub/Sub > Topics.
Next to a topic, click ⋮ and then click View permissions.
Click ADD PRINCIPAL.
Paste the Shopify service account address that you retrieved from the Partner Dashboard into the New principals text box.
In the Role drop-down list, select Pub/Sub and Pub/Sub Publisher.
Click Save.

You can now add webhook subscriptions to the Google Cloud Pub/Sub topic using Shopify's APIs.

Step 3: Create and manage subscriptions

Anchor link to section titled "Step 3: Create and manage subscriptions"

Subscribe to webhooks after you've integrated your app with Google Cloud Pub/Sub. You can subscribe to, update, and delete webhook subscriptions. Webhook data is divided by topic. Refer to the GraphQL Admin API or REST Admin API reference for the complete list of supported webhook topics.

The following examples show you how to subscribe to, update, and delete a webhook with GraphQL and REST.

Anchor link to section titled "Subscribe to a webhook"

The following examples show you how to subscribe to webhooks using GraphQL and REST.

Use the pubSubWebhookSubscriptionCreate mutation to create a new webhook subscription using GraphQL, with the following values:

Set pubSubProject to the ID of your Google Cloud Platform project
Set pubSubTopic to the ID of the topic that you set up in Google Cloud Pub/Sub.

Request: POST /admin/api/2023-01/graphql.json

Subscribing to a webhook using the REST API and Pub/Sub is similar to subscribing to HTTP webhooks, with the following differences:

Set the address field to pubsub://{project-id}:{topic-id}, where {project-id} is the ID of your Google Cloud Platform project
Set {topic-id} to the ID of the topic that you set up in Google Cloud Pub/Sub.

POST https://{store_name}.myshopify.com/admin/api/2023-01/webhooks.json

Update a webhook subscription

Anchor link to section titled "Update a webhook subscription"

Update a webhook subscription using GraphQL and REST.

Use the pubSubWebhookSubscriptionUpdate mutation to update a webhook subscription, with the following values:

Set pubSubProject to the ID of your Google Cloud Platform project.
Set pubSubTopic to the ID of the topic that you you set up in Google Cloud Pub/Sub.

Request: POST /admin/api/2023-01/graphql.json

Use the Webhook resource to update webhook subscriptions with REST.

For examples, refer to the reference documentation.

Delete a webhook subscription

Anchor link to section titled "Delete a webhook subscription"

Delete a webhook subscription using GraphQL and REST.

Use the webhookSubscriptionDelete mutation mutation to delete webhook subscriptions for Google Cloud Pub/Sub with GraphQL.

Use the Webhook resourceto update a webhook subscription with REST.

For examples, refer to the reference documentation

Google Cloud Pub/Sub message structure

Anchor link to section titled "Google Cloud Pub/Sub message structure"

During webhook serialization, Google Cloud Pub/Sub messages have the following structure:

Google Cloud Pub/Sub message fields
Field	Description
`data`	The webhook topic payload structure.
`attributes`	An object that contains key/value pairs of existing HTTP X-Shopify headers.
`messageId`	The ID of the message, assigned by the Google Pub/Sub server when the message is published.
`publishTime`	The time when the message was published, populated by the Google Pub/Sub server.
`orderingKey` Optional	The related messages for which publish order should be respected, populated by the Google Pub/Sub server.

Webhook topic payload structure

Anchor link to section titled "Webhook topic payload structure"

When you're using Google Cloud Pub/Sub to manage your webhooks, you receive a JSON payload for topics as described in the Webhook resource resource documentation. However, unlike with an HTTP webhook, you don't need to perform HMAC verification.

Refer to the Google Cloud Pub/Sub documentation for payload size limits.

Next steps

Anchor link to section titled "Next steps"

Test your configuration by manually triggering a webhook delivery using the Shopify CLI webhook trigger command. Manually triggering webhooks doesn't test your webhook subscriptions.
Learn how to manage webhooks for different API versions.
Learn about the available topics for REST Admin API webhooks.
Learn about the available topics for GraphQL Admin API webhooks.