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:
- In your Partner Dashboard, go to Apps.
- Click the name of your app.
- Click App setup.
- In your Shopify admin, go to Settings.
- Click Apps and sales channels.
- Click Develop apps for your store.
- Click the name of your app.
- Click Configuration.
- 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.
Subscribe to a webhook
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 projectSet
pubSubTopic
to the ID of the topic that you set up in Google Cloud Pub/Sub.
Request: POST /admin/api/2023-10/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 topubsub://{project-id}:{topic-id}
, where{project-id}
is the ID of your Google Cloud Platform projectSet
{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-10/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-10/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:
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.
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.