Merge pull request #1064 from Shopify/liz/additional-hmac-logging

Add additional HMAC validation logging
Shopify · Nov 27, 2023 · 05e3a1f · 05e3a1f
2 parents 6adccd7 + b4f10aa
commit 05e3a1f
Show file tree

Hide file tree

Showing 3 changed files with 15 additions and 1 deletion.
diff --git a/.changeset/fifty-seals-promise.md b/.changeset/fifty-seals-promise.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/shopify-api/docs/guides/webhooks.md b/packages/shopify-api/docs/guides/webhooks.md
@@ -136,3 +136,13 @@ await shopify.webhooks.process({
 ```
 
 [Back to guide index](../../README.md#guides)
+
+## Gotchas
+
+### Admin created webhook failing HMAC validation
+
+Webhooks subscriptions created in the [Shopify admin](https://help.shopify.com/en/manual/orders/notifications/webhooks) will fail HMAC validation. This is because the webhook payload is not signed with your app's secret key.
+
+Create webhook subscriptions using the `shopify.webhooks.register` method instead.
+
+Test your webhooks with the [Shopify CLI](https://shopify.dev/docs/apps/tools/cli/commands#webhook-trigger) or by triggering events manually in the Shopify admin(e.g. Updating the product title to trigger a `PRODUCTS_UPDATE`).
diff --git a/packages/shopify-api/lib/webhooks/validate.ts b/packages/shopify-api/lib/webhooks/validate.ts
@@ -51,7 +51,9 @@ export function validateFactory(config: ConfigInterface) {
       await log.debug('Webhook request is valid', loggingContext);
       return webhookCheck;
     } else {
-      await log.debug('Webhook validation failed', loggingContext);
+      await log.debug(
+        "Webhook HMAC validation failed. Please note that events manually triggered from a store's Notifications settings will fail this validation. To test this, please use the CLI or trigger the actual event in a development store.",
+      );
       return {
         valid: false,
         reason: WebhookValidationErrorReason.InvalidHmac,