In Google Cloud, create a Pub/Sub topic and grant the Shopify service account (`shopify-pubsub@shopify-tiers.iam.gserviceaccount.com`) the `pubsub.topics.publish` IAM role on the topic
Call `pubSubWebhookSubscriptionCreate(topic: ORDERS_CREATE, webhookSubscription: { pubSubProject: "my-gcp-project", pubSubTopic: "shopify-orders", format: JSON, includeFields: ["id", "email", "total_price"] })` with `write_fulfillments` or the appropriate topic-scoped scope
Alternatively, in API version 2025-10+, use the unified `webhookSubscriptionCreate` mutation with `uri: "pubsub://my-gcp-project:shopify-orders"` instead of the dedicated pubSub mutation
Verify the subscription was created by querying `webhookSubscriptions(first: 10, topics: [ORDERS_CREATE])` and confirming your Pub/Sub topic appears
In your Cloud Function or Pub/Sub subscriber, base64-decode the incoming message `data` field to access the Shopify webhook payload, and validate the `X-Shopify-Hmac-Sha256` header if the message is forwarded via an intermediary
Subscribe to the `webhook_failures` topic or set up Dead Letter Topics in Pub/Sub to catch any delivery failures
Known gotchas
pubSubWebhookSubscriptionCreate is deprecated as of the 2025-10 API version — Shopify now recommends using webhookSubscriptionCreate with a `pubsub://` URI scheme for all new integrations
The Shopify Pub/Sub IAM service account email varies by Shopify plan tier — verify the correct account from the Shopify developer docs for your plan before granting IAM permissions
Shopify delivers webhooks to Pub/Sub at-least-once; your subscriber must be idempotent using the `X-Shopify-Webhook-Id` header to deduplicate repeated deliveries
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp