2ff18f82dc of the integrations-roadmap worktree. Roadmap checked: roadmap.md v7, sections 5 and 6.F/ = packages/functions/src/.| # | Claim | Verdict | Roadmap change needed |
|---|---|---|---|
| 1 | Shopify webhook retries, timeout, subscription deletion | CONFIRMED | No (add the numbers) |
| 2 | HMAC on raw body, 401 on bad HMAC, duplicate guidance | PARTLY | Yes: dedupe key is X-Shopify-Webhook-Id, Joy uses X-Shopify-Event-Id |
| 3 | Cloud Tasks task size | CONFIRMED (1 MiB), with a Google doc conflict | Small |
| 4 | GraphQL throttling and bulk tag updates | PARTLY | Yes: THROTTLED arrives as HTTP 200; existing bulk tag path uses customerUpdate, not tagsAdd |
| 5 | Flow action status handling | PARTLY | Yes: retry window is 36 h; timeouts and 429 are also resent |
| 6 | Gorgias invalid_client, token lifetimes, rate limits |
PARTLY (meaning of invalid_client UNVERIFIABLE in Gorgias docs) |
Yes: soften "points at Joy's client" |
| 7 | Instagram token lifetime, refresh rules, error codes, signature | CONFIRMED | Yes: 2.7 lacks a proactive refresh |
| 8 | Review-app webhook signing | PARTLY | Yes: Fera can be verified today (JWT); Yotpo cannot |
| 9 | Recharge webhook verification and scopes | PARTLY | Yes: it is not a keyed HMAC, and it needs a secret Joy does not store |
| 10 | Loop signature header, topic name, listing | PARTLY | Yes: topic is return, trigger is return.closed; no "customer chose exchange" field |
| 11 | Tapcart blocks, customer session, partner program | PARTLY (session contents UNVERIFIABLE) | No (the spike is the right step) |
| 12 | Okendo Flow trigger, loyalty connector | CONFIRMED | Small: trigger fires on submit, before moderation |
| 13 | App Store / BFS rules touched by non-2xx or the health banner | PARTLY | Yes: compliance webhooks must answer 401; banner count rule |
| 14 | Cloud Tasks dedupe window, at-least-once, retries, rate limits | CONFIRMED | Yes: a 429 returned to Cloud Tasks throttles the whole queue |
Three findings change a fix rather than its wording: claim 2 (dedupe key), claim 8 (Fera), claim 9 (Recharge secret). They are repeated in the last section.
Verdict: CONFIRMED.
Docs — https://shopify.dev/docs/apps/build/webhooks/subscribe/https
Joy today (Local):
webhookSubscriptionCreate, F/services/shopify/graphqlService.js:2102-2103, also :5008). No shopify.app*.toml is tracked in this worktree, so no app-config subscription was found. The deletion rule therefore applies to Joy.F/middleware/webhook/enqueueWebhookToCloudTasks.js:46-58).apiHookV2 has a 30-second function timeout (F/entries/http-webhooks.js:33-34), six times Shopify's 5-second limit.Roadmap check: item 2.20 ("Shopify deletes API-created subscriptions after repeated failures", shadow week first, daily subscription check) matches the docs.
Suggested addition to 2.20, not a correction: "Shopify counts any non-2xx, including 3xx, and any answer slower than 5 seconds as a failure, retries 8 times over 4 hours, and deletes an Admin-API subscription after 8 consecutive failures. The shadow mode must therefore also count answers slower than 5 seconds, because they already count toward deletion today."
Verdict: PARTLY. The HMAC and 401 parts are confirmed. The dedupe key is not the one Joy uses.
Docs — https://shopify.dev/docs/apps/build/webhooks/subscribe/https
X-Shopify-Hmac-SHA256 header, generated using your app's client secret and the raw request body."res.status(401).send('HMAC validation failed.') and compares with crypto.timingSafeEqual.Docs — https://shopify.dev/docs/apps/build/webhooks/ignore-duplicates
X-Shopify-Webhook-Id to deduplicate individual deliveries."X-Shopify-Event-Id to correlate deliveries that originated from the same merchant action."Joy today (Local):
JSON.stringify(ctx.req.body), compared with Array.includes, which is not timing-safe (F/middleware/webhook/verifyHook.js:40-52).F/middleware/webhook/verifyHook.js:135-140).eventId and falls back to webhookId, scoped by shop domain only, not by topic (F/repositories/webhookLogRepository.js:20-37). The log is written before the work is queued (F/middleware/webhook/verifyHook.js:141-151).What this means (Inference): Shopify says X-Shopify-Event-Id is shared by every delivery that came from one merchant action. Joy treats the second delivery with the same event id as a duplicate and drops it, even when it is a different subscription. Whether one action produces two orders/* deliveries with one event id was not observed; it must be measured before 2.19 fixes the dedupe record.
Corrected wording for 2.19: "Key the dedupe record on X-Shopify-Webhook-Id (the delivery), as Shopify documents; keep X-Shopify-Event-Id only for correlation. Before the change, count in the shadow mode how many deliveries are dropped today because they share an event id with a different webhook id or topic."
Corrected wording for 2.20: "A bad HMAC gets 401. Verify against the raw body only and compare timing-safe; drop the second accepted form (HMAC of the re-serialised JSON) after the shadow week shows nothing depends on it."
Verdict: CONFIRMED at 1 MiB, with a conflict between two Google pages.
Docs — https://docs.cloud.google.com/tasks/docs/quotas : maximum task size "1 MiB", described as "The maximum size of a task that can be added to a queue."
Docs — https://docs.cloud.google.com/tasks/docs/reference/rest/v2/projects.locations.queues.tasks/create : "The maximum task size is 100KB."
The two pages disagree. The quotas page is the one Google maintains as the limit table, and the 303 production failures named "Task size too large" on large order payloads are consistent with either number. Treat 1 MiB as the limit and 100 KB as stale reference text, and do not design to the edge of either.
Joy today (Local): the whole ctx.state (shop document plus order payload) is the task body (F/middleware/webhook/enqueueWebhookToCloudTasks.js:34-43).
Roadmap check: 2.19 ("enqueue a small reference task", "measure the envelope size on staging") and 3.4 ("one size limit applies at enqueue") are consistent. Suggested addition to 3.4: "Set the enqueue size limit well under 100 KB, because Google's pages state both 1 MiB and 100 KB."
Verdict: PARTLY. Limits and bulk feasibility are confirmed. Two details the roadmap does not state would break the first slice of 2.18.
Docs — https://shopify.dev/docs/api/usage/response-codes
200 OK and report it in the response body as a THROTTLED error instead."{"errors":[{"message":"Throttled","extensions":{"code":"THROTTLED"}}]}.Docs — https://shopify.dev/docs/apps/build/apis/graphql-admin/rate-limits
extensions.cost.throttleStatus carries maximumAvailable, currentlyAvailable, restoreRate.Docs — https://shopify.dev/docs/api/usage/limits : "The recommended backoff time is one second." "Input arguments that accept an array have a maximum size of 250, on every Shopify API."
Docs — https://shopify.dev/docs/api/usage/bulk-operations/imports
Joy today (Local):
{} (F/services/shopify/shopifyMetaFieldService.js:3511-3519).tagsAdd / tagsRemove (F/services/shopifyService.js:3705, :3750), called in pairs from F/services/shopifyService.js:3302-3305.tagsAdd. It sends customerUpdate with the full tags array (F/services/shopify/bulkMetafieldService.js:471-477, flow at :499).throttleStatus is read in one place only (F/handlers/pubsub/subscribeRecursive.js:507-508).What this means:
errors[].extensions.code.tagsAdd through a bulk mutation is feasible, since any mutation is allowed. It is not what "the existing tier-tag bulk machinery" does. customerUpdate with a tag array replaces the customer's tags, so a merchant's own tag edit made between Joy's read and the bulk write is lost (Inference from the mutation's replace semantics).Corrected wording for 2.18: "Errors stay typed and retryable: detect a throttle from errors[].extensions.code == THROTTLED on an HTTP 200 answer, not from the status. The per-shop queue admits work against extensions.cost.throttleStatus (one bucket per app and shop, restore rate 100 to 2,000 points a second by plan) and waits at least one second after a throttle. Mass tag runs go through a bulk mutation built on tagsAdd / tagsRemove; the existing bulk tag code uses customerUpdate with the full tag array and must not be reused as-is, because it overwrites tags changed in between. On API versions before 2026-01 only one bulk mutation runs per shop at a time, so the run must queue behind Joy's own metafield and tier bulk jobs."
Verdict: PARTLY. The roadmap's rule (use a 4xx, not a 5xx) is right. The retry window and two more resend cases are missing.
Docs — https://shopify.dev/docs/apps/build/flow/actions/endpoints
message."Retry-After the wait "only supports wait times between 5 and 3600 seconds (1 hour)."action_run_id as an idempotency key to check if the request is unique."Joy today (Local):
action_run_id before the handler runs and answers a repeat with HTTP 200 "Webhook duplicated" (F/middleware/webhook/verifyHookShopifyFlow.js:44-62).success: false (F/controllers/shopifyFlowController.js:1198-1203); the correct pattern answers 400 with message (:1156-1159).F/controllers/shopifyFlowController.js:135-143).F/entries/http-integrations.js:24-27), the same as Flow's wait.Array.includes (F/middleware/webhook/verifyHookShopifyFlow.js:37-43). Roadmap section 2.3 lists Flow as "signed and timing-safe"; at HEAD the comparison is not timing-safe.What this means (Inference): an action that takes longer than 10 seconds, or that answers 429, is resent by Flow. Joy's middleware has already stored the action_run_id, so the resend gets "duplicated" with HTTP 200 and Flow records a success for work that may not have finished. This is the same trap 2.13 names for 5xx, on two more paths.
Corrected wording for 2.13: "Return a 4xx (not 429) with a message key when an action fails; Flow shows the raw response to the merchant and does not resend. Do not use 5xx, 429 or 202, and do not exceed 10 seconds: Flow resends those for up to 36 hours, and the middleware would answer the resend as a duplicate with 200. Move the action_run_id marker to after the handler completes (the acceptance contract of 2.19), so a resend after a timeout is processed instead of acknowledged. A bad HMAC gets 401."
Item 4.2's "402 with an upgrade message" is consistent: 402 is an "other 4XX", so it is not resent and its message is shown.
Verdict: PARTLY. Token lifetimes and rate limits are confirmed. The meaning of invalid_client is UNVERIFIABLE in Gorgias's docs.
Docs — https://developers.gorgias.com/docs/set-up-oauth2-app-store
access_token retrieved here is only valid for 24 hours, and will need to be renewed after that."refresh_token does not expire for now."Client ID and Client Secret)."access_token expires as it is stateless."Docs — https://developers.gorgias.com/docs/oauth2-authentication-for-creating-apps-with-gorgias : "In case the application is deactivated on the helpdesk, in order to obtain the access token again, the entire process for obtaining an access token needs to be repeated." The refresh response example has no refresh_token field.
Docs — https://developers.gorgias.com/reference/limitations : "OAuth2 apps can make 80 requests in a 20 second window"; "API key integrations can make 40 requests in a 20 second window"; "Enterprise accounts folow the same request limits, but have a smaller 10-second window". Headers: Retry-after and X-Gorgias-Account-Api-Call-Limit.
invalid_client: neither OAuth page nor https://developers.gorgias.com/reference/errors lists OAuth error codes. In the OAuth 2.0 standard (RFC 6749 section 5.2) it means client authentication failed. Gorgias does not say when it returns it.
Joy today (Local):
https://{subDomain}.gorgias.com/oauth/token with Basic client auth and keeps the old refresh token (F/services/gorgiasService.js:198-232), which matches the docs.undefined (F/services/gorgiasService.js:235-237).F/services/gorgiasService.js:26-32).What this means (Inference): the same client id and secret are sent for every account, and only 8 of 58 connected accounts fail. A dead Joy client would fail all of them. The token endpoint is per subdomain, so an account-level cause (app uninstalled or deactivated on that helpdesk, subdomain renamed, account closed) fits the data at least as well. The header name X-Gorgias-Account-Api-Call-Limit suggests the limit is counted per account, which a per-instance limiter cannot respect.
Corrected wording for 2.6 "Why": "invalid_client on 8 accounts since 2026-11-05 01:46 UTC, none before. Gorgias does not document this error; in OAuth 2.0 it means client authentication failed. Because the other connected accounts refresh with the same client, test account-level causes first (app uninstalled or deactivated on that helpdesk, subdomain changed) by refreshing one healthy account and comparing." Decision 3 should carry the same test. Item 1.8 can then tell the 8 shops to reinstall the app, which the docs say requires the whole authorization flow again.
Verdict: CONFIRMED. One gap in the fix.
Docs — https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login/business-login
GET to /refresh_access_token with grant_type set to ig_refresh_token.Docs — https://developers.facebook.com/docs/graph-api/guides/error-handling (page was served in Vietnamese; meanings given in English): code 190 = access token expired, get a new token. Subcode 460 = password changed, the user must log in to the app again. Subcode 463 = expired; the login status or token has expired, been revoked or is invalid. Subcode 467 = invalid access token. Codes 4 and 17 = too many calls, temporary, wait and retry.
Docs — https://developers.facebook.com/docs/graph-api/webhooks/getting-started
X-Hub-Signature-256 header, preceded with sha256=."Joy today (Local):
F/services/instagram/instagramApiService.js:63-77); on failure the old token is returned (:102-105).sha256= prefix, timing-safe (F/helpers/social/verifyWebhookSignature.js:12-25), which matches the docs.What this means (Docs + Local): Joy's refresh window is the last 24 hours of a 60-day token, and only if the integration is used inside that window. A shop with no Instagram activity that day passes the expiry, and Meta then refuses the refresh for good. Marking auth_broken (2.7) reports this; it does not prevent it.
Suggested addition to 2.7: "Add a scheduled refresh for tokens that are more than 24 hours old and have less than about 30 days left; an expired token cannot be refreshed and needs a new login. Treat error 190 (subcodes 460, 463, 467) as auth_broken, and codes 4 and 17 as transient."
Not confirmed: which app secret signs webhooks for Instagram Login apps. The Instagram webhooks page only says "Your endpoint must validate notification signatures."
Verdict: PARTLY. Judge.me and Klaviyo Reviews are confirmed. The roadmap's plan for Fera is wrong, and for Yotpo it is the only option.
| App | What the partner documents | Source | Joy today (Local) |
|---|---|---|---|
| Judge.me | Header JUDGEME-HMAC-SHA256; examples use a hex HMAC-SHA256 of the raw body and answer 401. "If the webhook was created through an OAuth app, use the OAuth app's secret key"; if created with the store's Private API token, "use that same Private API token as the secret." |
https://judge.me/help/en/articles/8299679-verifying-webhooks-from-judge-me | No signature check (F/middleware/webhook/verifyHookReviewApp.js:17-57). Webhooks are registered with the OAuth access token (F/services/reviews/judge.js:77-105) |
| Klaviyo Reviews | Headers Klaviyo-Signature, Klaviyo-Timestamp, Klaviyo-Webhook-Id; HMAC-SHA256 "using the request body, your secret_key, and the timestamp". Expects 200, 201 or 202 "within 5 seconds"; a webhook in error for over 48 hours is disabled. "only Advanced KDP customers and Klaviyo app partners can access and manage webhooks with our Webhooks API." |
https://developers.klaviyo.com/en/docs/working_with_system_webhooks | Body then timestamp, hex, matches the docs (F/middleware/webhook/verifyKlaviyoWebhook.js:16-29). Skipped when no secret is found (:108-125) |
| Fera | "When Fera POSTs to a webhook URL it will include a JWT token as a the jwt URL parameter." The JWT "uses Standard HS256 (HMAC SHA256) encryption", signed with the store's Secret Key (or the Client Secret for partner apps), with claims webhook_id, event_name, store_domain, store_id, exp; it expires after one hour |
https://developers.fera.ai/reference/webhooks and https://developers.fera.ai/docs/webhook-structure | No check. Joy already stores the store's Fera secret key and uses it for the connect test (F/services/reviews/fera.js:15-17) |
| Yotpo | Headers X-Yotpo-Webhooks-Event-Type, X-Yotpo-Webhooks-Tenant-Type, X-Yotpo-Webhooks-Tenant-Id, WebhookMessageId, WebhookMessageIdPerTarget ("Use it to ignore duplicates."). No signature or secret is described. "If Yotpo doesn't get a 200", it retries at least 10 times with exponential backoff. Target URLs must be HTTPS and at most 2048 characters |
https://docs.yotpo.com/from/developer/reference/yotpo-events and https://docs.yotpo.com/docs/about-webhook-events | No check; a processing error is answered 200 (F/middleware/webhook/verifyHookReviewApp.js:54-57) |
| Loox | "add a validation key to verify that incoming webhooks are from Loox." Without a key, "webhooks are delivered unsigned." "Available on the Convert and Unlimited plans." The merchant sets the key in Loox admin, Settings > API Keys > Webhooks | https://help.loox.io/support/solutions/articles/501000356871-loox-reviews-api-and-webhooks | Header x-loox-signature, hex HMAC-SHA256, timing-safe, only when a key is stored (F/middleware/webhook/verifyHookLoox.js:15-25, :70-85) |
| Stamped | Headers on every push: X-Secret-Key, X-Stamped-Webhook-Secret, X-Stamped-Store-Url, X-Shopify-Shop-ID, X-Stamped-Topic. "Enter a secret only if the application or service receiving your webhook requires one for validating incoming requests." No body HMAC is described |
https://stampedsupport.stamped.io/hc/en-us/articles/10152800778395-Webhooks | No ingestion path (roadmap section 1) |
| Air Reviews | Avada's own app; no public developer docs | none | Header X-Air-Reviews-Hmac-Sha256, HMAC-SHA256 (F/services/reviews/airReview.js:125-151) |
| Review Rocket | No developer or webhook documentation found | none | No check |
Verdict per part:
JUDGEME-HMAC-SHA256 header; the secret depends on the registration mode") matches. One constraint to add (Inference): Joy registers through its OAuth app, so the signing secret is Joy's one Judge.me client secret for every shop. The signature proves the sender is Judge.me, not which shop the review belongs to; the tenant must still be bound from the payload.x-loox-signature rests on Joy's code and the 17 rejections in prod. Item 2.11 is consistent: the merchant must paste the key in Loox admin, Joy cannot set it.Corrected wording for 3.8: "… and Loox (full enforcement). Fera moves into this item: verify the jwt URL parameter (HS256, signed with the store's Fera secret key that Joy already stores), check exp and that store_domain matches the tenant. Only Yotpo and Review Rocket have no signing; they get a per-shop secret in the registered URL next quarter, and dedupe on Yotpo's WebhookMessageIdPerTarget." Change the two "URL tokens for Yotpo and Fera" lines (3.8 and the deferred list) to "URL tokens for Yotpo and Review Rocket".
Constraint for all review sources: Yotpo retries only when it "doesn't get a 200", and Joy answers 200 on a processing error, so the partner's retry is never used. The verifier contract's "accept durably before acknowledging" covers this.
Verdict: PARTLY. The header name is right. The algorithm is not a keyed HMAC, and the secret is one Joy does not have.
Docs — https://docs.getrecharge.com/docs/webhooks-overview
X-Recharge-Hmac-Sha256 header which is generated using the API Client Secret".hash('sha256',$client_secret.$request_body);. This is a plain SHA-256 of secret plus body, not HMAC(secret, body).Docs — https://developer.rechargepayments.com/2021-11/webhooks_explained : "To use these webhooks your API Token must have read permissions for Orders enabled ( read_orders )."
Joy today (Local):
F/routes/apiHookV1.js:627).shopId from the query, logs the order, and never sets a status or body, also when it fails (F/controllers/integrationController.js:769-778).order/created webhook with the merchant's API token (F/services/integrate/rechargeService.js:92-108, token sent as X-Recharge-Access-Token at :449). No client-secret field exists in the Recharge service.What this means:
createHmac('sha256', secret), like every other Joy verifier, will reject every genuine Recharge delivery.Corrected wording for the Recharge part of 3.8: "Recharge: answer 200 within 5 seconds once the work is accepted (Recharge resends 20 times over 48 hours and then deletes the webhook). Verify X-Recharge-Hmac-Sha256 as the hex SHA-256 of the API Client Secret concatenated with the raw body; this is not a keyed HMAC. Collect the API Client Secret at connect (it is not the API token Joy stores), run dual-accept until each shop has supplied it, and take the tenant from the verified credential instead of the shopId query. The API token needs read_orders for order/created."
Verdict: PARTLY. Header and trigger are confirmed. The wording and the payload assumption need a fix. The listing process is UNVERIFIABLE.
Docs — https://docs.loopreturns.com/webhook-reference/validation
X-Loop-Signature header."Docs — https://docs.loopreturns.com/webhook-reference/getting-started
return.created, return.updated, return.closed.Docs — https://docs.loopreturns.com/openapi/return-webhook.yaml
state values: open, cancelled, closed, review, expired.exchanges: "Details about the product(s) being sent to the customer." gift_card: "The amount of store credit to be issued to the customer on a gift card." refund: "The total refund value of the return."customer: "The email address of the customer." provider_order_id: "The order ID from the commerce provider (e.g. Shopify)."Joy today (Local): no Loop code exists. The planned route sits beside F/routes/apiHookV1.js:627.
What this means:
return.closed topic. The topic is return and the trigger is return.closed. A subscription to both return.updated and return.closed delivers a close twice.exchanges array or a gift_card amount above zero, with state equal to closed. Mixed returns carry both a refund and an exchange, which the roadmap's demand gate already lists as a rule to agree.Corrected wording for 4.7: "An inbound Loop webhook on the return topic with the return.closed trigger only, verified with X-Loop-Signature (base64 HMAC-SHA256 of the raw body with the merchant's Loop webhook secret, which the merchant supplies at connect). Award points when state is closed and the payload has a non-empty exchanges array or a positive gift_card amount; identify the customer by customer (email) and provider_order_id. Answer within 10 seconds and dedupe by return id, because delivery is at-least-once."
Verdict: PARTLY. The block and partner programme exist. What the customer session carries is UNVERIFIABLE from the docs, which is what the roadmap's spike is for.
Docs — https://dev.tapcart.com/docs/customer
customer.customerSession is listed as "Authentication tokens and session data" (object), available "When logged in".customer variable will be undefined."Docs — https://www.tapcart.com/blog/tech-partner-program (dated September 25, 2023): "The Tech Partner Program is structured into three tiers: Elite Partner, Preferred Partner, and Core Partner." Developer tools named: "Custom Blocks, Web Bridge SDK, Insights Data Streaming, and more." Application through a form.
Not fetched first-hand: the plan requirement. A search result for https://docs.tapcart.com/docs reports that custom blocks and the CLI need an Enterprise plan; treat this as a lead to confirm in the spike.
Joy today (Local): the headless token grant is at F/controllers/headless/headlessAuthController.js:33-36 and F/services/headless/headlessAuthService.js:20-27 (as cited by the roadmap; not re-read for this report).
Roadmap check: 4.3 starts with "a spike to learn what Tapcart's customerSession carries". That is correct and necessary. Suggested addition: "The spike must answer one question first: is there anything in customerSession that Joy's server can verify with Shopify without a secret in the block? If not, the block cannot prove identity and the design changes. Also confirm the Tapcart plan that custom blocks require, since it bounds the number of shops the block can reach." The partner-programme page is three years old; the application route in 4.1 should be reconfirmed with Tapcart.
Verdict: CONFIRMED.
Docs — https://support.okendo.io/en/articles/4904493-how-to-use-the-okendo-review-created-shopify-flow-trigger
{{trigger.rating}}, {{trigger.email}}, {{trigger.source}}, {{trigger.achievedReward}}, {{product.title}}.Docs — https://support.okendo.io/en/articles/8197562-award-yotpo-loyalty-points-for-okendo-reviews-using-shopify-flow : Okendo documents awarding a third-party loyalty app's points through this Flow trigger. No native connector for third-party loyalty apps was found; Okendo sells its own loyalty product.
Joy today (Local): the template to copy is extensions/flow-template-loox/shopify.extension.toml; the action is the reward-by-program handler ending at F/controllers/shopifyFlowController.js:1150-1160.
Roadmap check: 4.2 (a Flow template, no native connector) and the deferral of N-07 match the docs.
Suggested addition to 4.2 (Inference from the approve and reject links): "The Okendo trigger fires when the review is submitted, before moderation. The template should filter on rating and document that a rejected review has already been rewarded; no approved-review trigger was found."
Verdict: PARTLY. No rule penalises a non-2xx answer to ordinary webhooks. Two rules do touch the roadmap.
Docs — https://shopify.dev/docs/apps/build/compliance/privacy-law-compliance
HMAC header, then the app must return a 401 Unauthorized HTTP status."200 series status code."Docs — https://shopify.dev/docs/apps/launch/built-for-shopify/requirements
Joy today (Local):
F/middleware/webhook/verifyHook.js:135-140).shopify.app*.toml is tracked in this worktree. customers/redact is processed off the task queue (F/services/customer/customerRedactService.js:267).packages/assets/src/components/BannerNotice/BannerIntegrationDisconnected.js:30 (as cited by the roadmap).What this means:
verifyHook, Joy answers 200 to an invalid HMAC, which the App Store requirement forbids. Item 2.20 fixes it; that makes 2.20 a compliance item as well as a reliability one. Confirm the route first.Suggested addition to 2.20: "The 401 for a bad HMAC is also an App Store requirement for the mandatory compliance webhooks; confirm that those topics use this verifier." Suggested addition to 3.10: "One Home banner at most, listing every app that needs action; it stays until fixed or dismissed, is red for errors and links to the fix. The health data must not add a blocking request to the Home page load (LCP 2.5 seconds)."
Verdict: CONFIRMED.
Docs — https://docs.cloud.google.com/tasks/docs/quotas
Docs — https://docs.cloud.google.com/tasks/docs/reference/rest/v2/projects.locations.queues.tasks/create
google.rpc.Code.ALREADY_EXISTS."Docs — https://docs.cloud.google.com/tasks/docs/common-pitfalls : Cloud Tasks "errs on the side of guaranteed execution"; "As such, a non-zero number of duplicate executions do occur." Dispatches "ramp up slowly when the queue is newly created or idle".
Docs — https://docs.cloud.google.com/tasks/docs/reference/rest/v2/projects.locations.queues
maxDispatchesPerSecond: "The maximum allowed value is 500." maxConcurrentDispatches: "The maximum allowed value is 5,000."Docs — https://docs.cloud.google.com/tasks/docs/configuring-queues : max_attempts is "the maximum number of attempts for a task, including the first. To allow unlimited retries, set this to -1."
Joy today (Local):
F/entries/tasks.js:16-24).F/services/cloudTaskService.js:51-52).maxAttempts: 3 and maxDispatchesPerSecond: 0.8 (F/const/pointExpiration.js:39-43).Roadmap check: section 3.3 (500 per second, 1,000 queues), decision 2 in 5.3 ("its reuse is blocked for up to 24 hours", "a task can run more than once") and risk 2 all match the docs.
One constraint the roadmap does not state (Docs): the worker must never pass a partner's 429 or 503 through as its own HTTP answer to Cloud Tasks. Cloud Tasks reads those two codes as a signal to slow the whole queue, which would stall every shop and app on the shared delivery queue because one partner throttled one shop. It would also consume an attempt.
Suggested addition to the delivery worker (5.2 and 3.4): "On a partner 429 the worker creates a new task with a new attempt id and a scheduleTime after Retry-After, records the deferral, and answers 2xx to Cloud Tasks. It never answers 429 or 503 itself, because Cloud Tasks throttles the whole queue on those codes. A deferral cannot be scheduled more than 30 days ahead, and a new queue ramps up slowly, so the first cut-over must not start with a backlog."
Ordered by how much they change the work.
X-Recharge-Hmac-Sha256 is SHA-256 of the API Client Secret concatenated with the body. Joy stores only the API token. Enforcement needs a new credential from each connected shop.X-Shopify-Webhook-Id; Joy dedupes on X-Shopify-Event-Id, per shop, across topics (claim 2, affects 2.19 and 2.20). Deliveries that share an event id may be dropped as duplicates today. Measure before changing the dedupe record.jwt URL parameter, HS256, signed with the store secret key Joy already stores. No URL token and no merchant action are needed.errors[].extensions.code = THROTTLED (claim 4, affects 2.18). Classification by status code misses it.customerUpdate with the full array. Reusing it for mass tag runs can erase a merchant's concurrent tag edit; use tagsAdd / tagsRemove in the bulk mutation.action_run_id is stored before the handler runs, so a resend after a slow action is acknowledged as a duplicate.auth_broken will keep being reached by idle shops.Retry-after.exchanges, gift_card and state, and the signing secret is per merchant.invalid_client is the OAuth 2.0 standard's, not Gorgias's.customerSession. The Enterprise-plan requirement for custom blocks comes from a search result, not a fetched page.orders/* deliveries with the same event id. Finding 3 above needs the shadow-mode count.verifyHook? The app configuration file is not in this worktree.