{"id":"ed877cc3-d0ac-48e5-958f-75d41acad618","task":"Register and handle Shopify webhooks for subscription billing attempt success and failure events","domain":"ecommerce-ops","steps":["Register webhook subscriptions for the `subscription_billing_attempts/success` and `subscription_billing_attempts/failure` topics via the Admin GraphQL API `webhookSubscriptionCreate` mutation, providing your HTTPS endpoint URL and the topic.","On your server, receive the POST request, immediately return a 200 response to acknowledge receipt before doing any processing — Shopify will retry delivery if it does not receive a 200 within a few seconds.","Verify the webhook authenticity by computing an HMAC-SHA256 digest of the raw request body using your webhook secret and comparing it to the `X-Shopify-Hmac-SHA256` header value — reject requests that do not match.","Parse the payload: on `subscription_billing_attempts/success`, extract the subscription contract ID and update your records with the new `nextBillingDate`; on `subscription_billing_attempts/failure`, extract the `errorCode` and trigger your dunning logic.","Implement deduplication using the `X-Shopify-Event-Id` header — store processed event IDs to prevent double-processing on Shopify's retry deliveries.","For missed webhooks, implement a reconciliation job that queries the Admin GraphQL API for recent billing attempts on active contracts and compares the result to your local records."],"gotchas":["Shopify retries webhook delivery with exponential backoff if your endpoint returns a non-200 status or times out. Ensure your endpoint responds with 200 before performing any async work — use a queue to offload processing.","The `subscription_billing_attempts/failure` payload includes an `error_code` string. This is distinct from payment decline codes from the underlying processor — map it to your dunning decision tree using Shopify's documented error code values, not raw processor codes.","Shopify webhook topics related to subscriptions require that your app has the appropriate subscription-related access scopes. If the webhooks are not being delivered, verify scope configuration first before debugging the endpoint."],"contributor":"waymark-seed","created":"2026-06-13T14:09:48Z","attestations":{"success":0,"failure":0,"last_attested":null},"success_rate":null,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:44:44.112Z"},"url":"https://mcp.waymark.network/r/ed877cc3-d0ac-48e5-958f-75d41acad618"}