技能 编程开发 Shopify Webhooks与事件系统集成

Shopify Webhooks与事件系统集成

v20260423
shopify-webhooks-events
本指南详细介绍了Shopify应用中事件驱动的后端集成方法。内容涵盖如何使用GraphQL注册订单、产品等关键事件的Webhook订阅,实现稳健的HMAC验证,并重点指导了如何配置满足App Store要求的GDPR合规处理流程。适用于构建高性能的电商后台系统。
获取技能
68 次下载
概览

Shopify Webhooks & Events

Overview

Register webhooks via GraphQL, handle events with HMAC verification, and implement the mandatory GDPR compliance webhooks required for Shopify App Store submission.

Prerequisites

  • Shopify app with API credentials configured
  • HTTPS endpoint accessible from the internet (use shopify app dev tunnel for local)
  • API secret for HMAC webhook verification

Instructions

Step 1: Register Webhooks via GraphQL

Use the webhookSubscriptionCreate mutation with WebhookSubscriptionTopic and WebhookSubscriptionInput to register subscriptions for all critical event topics (orders, products, customers, inventory, app lifecycle).

See Webhook Registration for the complete implementation.

Step 2: Configure Mandatory GDPR Webhooks

Required for App Store submission. These are configured in shopify.app.toml, not via API:

# shopify.app.toml
[webhooks]
api_version = "2025-04"  # Update quarterly

  # MANDATORY: customers/data_request
  [[webhooks.subscriptions]]
  topics = ["customers/data_request"]
  uri = "/webhooks/gdpr/data-request"

  # MANDATORY: customers/redact
  [[webhooks.subscriptions]]
  topics = ["customers/redact"]
  uri = "/webhooks/gdpr/customers-redact"

  # MANDATORY: shop/redact
  [[webhooks.subscriptions]]
  topics = ["shop/redact"]
  uri = "/webhooks/gdpr/shop-redact"

Step 3: Implement GDPR Webhook Handlers

Three mandatory handlers: (1) customer data request -- collect and send all data for a customer, (2) customer redact -- delete customer personal data and specified orders, (3) shop redact -- delete ALL shop data 48 hours after uninstall.

See GDPR Webhook Handlers for the complete implementation.

Step 4: Event Handler Pattern

A typed webhook dispatcher maps topics to handler functions. Verifies HMAC first, responds 200 immediately, then processes asynchronously. Unknown topics are logged but not rejected.

See Event Handler Pattern for the complete implementation.

Step 5: List and Manage Existing Webhooks

// Query all webhook subscriptions
const LIST_WEBHOOKS = `{
  webhookSubscriptions(first: 50) {
    edges {
      node {
        id
        topic
        endpoint {
          ... on WebhookHttpEndpoint { callbackUrl }
        }
        format
        createdAt
      }
    }
  }
}`;

// Delete a webhook
const DELETE_WEBHOOK = `
  mutation webhookSubscriptionDelete($id: ID!) {
    webhookSubscriptionDelete(id: $id) {
      deletedWebhookSubscriptionId
      userErrors { field message }
    }
  }
`;

Output

  • Webhook subscriptions registered for critical events
  • Mandatory GDPR webhooks implemented (required for App Store)
  • HMAC verification on all incoming webhooks
  • Async event processing with error handling

Error Handling

IssueCauseSolution
Webhook delivery failsEndpoint not reachableEnsure HTTPS, check tunnel is running
HMAC validation failsWrong API secretVerify SHOPIFY_API_SECRET in Partner Dashboard
Webhook not receivedTopic not registeredCheck webhookSubscriptions query
App Store rejectionMissing GDPR webhooksImplement all 3 mandatory handlers
Duplicate eventsShopify retries on timeoutAdd idempotency with webhook ID tracking
Timeout errorsHandler takes > 5 secondsRespond 200 immediately, process async

Examples

Test Webhook Locally

# Use Shopify CLI to trigger test webhooks
shopify app webhook trigger --topic orders/create --address http://localhost:3000/webhooks

# Or use curl with a test payload
curl -X POST http://localhost:3000/webhooks \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Topic: orders/create" \
  -H "X-Shopify-Shop-Domain: test.myshopify.com" \
  -H "X-Shopify-Hmac-Sha256: $(echo -n '{"test":true}' | openssl dgst -sha256 -hmac "$SHOPIFY_API_SECRET" -binary | base64)" \
  -d '{"test":true}'

Resources

信息
分类 编程开发
名称 shopify-webhooks-events
版本 v20260423
大小 4.95KB
更新时间 2026-09-06
语言