用途:帮助开发者在 Shopify 应用中接收并处理 Webhook 实时通知,例如 orders/create、app/uninstalled 等事件,以便与店铺数据保持同步。
主要能力:
- 校验:所有请求必须验证来源。Shopify 在请求头 X-Shopify-Hmac-Sha256 中携带以 Client Secret 为密钥、对请求体做 HMAC-SHA256 后 base64 编码的摘要。校验时必须使用原始请求体(Buffer),解析后的 JSON 可能因细微差异导致失败,可用 Node.js crypto 的 createHmac 与 timingSafeEqual 实现。若使用 @shopify/shopify-app-remix,authenticate.webhook 会自动完成校验。
- 注册:推荐在 shopify.app.toml 的 [webhooks] 中配置应用级订阅,例如 topics = [ "app/uninstalled", "orders/create" ]、uri = "/webhooks",随应用部署自动注册;需要按店铺定制、动态注册或配置不支持的主题时,使用 Admin API 的 webhookSubscriptionCreate 变更。
- GDPR 合规:公开应用必须在 Partner Dashboard(App > Configuration > Privacy compliance)配置 customers/data_request、customers/redact、shop/redact,不能通过 toml 或 API 配置。
使用方式:接收请求后先校验签名,再按主题分发处理,最后返回响应。
适用场景:需要实时响应订单创建、支付状态变化、商品更新、应用卸载等事件的 Shopify 应用。
限制与最佳实践:Webhook 可能重复投递,处理逻辑需保证幂等;应在 5 秒内立即返回 200 OK,耗时任务放入后台队列异步执行;务必处理 app/uninstalled 以清理数据并取消订阅;未处理 GDPR 合规可能导致应用被下架。资料未提供具体语言的完整运行环境、依赖版本与部署步骤。