DEV Community

Thomas
Thomas

Posted on Edited on

Shopify deletes API-created webhook subscriptions after 8 failures. An n8n safety net, no Code node

Picture a shop that keeps taking orders all weekend while your n8n container sits in a restart loop. Every delivery fails. Shopify retries 8 times over 4 hours, and "after 8 consecutive failures, the subscription is automatically deleted if it was configured using the Admin API." On Monday n8n is healthy again, and silent. Nothing ran, so nothing failed, so no error workflow fired.

That rule applies to shop-specific subscriptions, the ones created with webhookSubscriptionCreate: the usual route when there is no app project (no shopify.app.toml, no CLI). App-specific ones are treated differently (next section).


What this post builds, with native nodes only (no Code node)
  • A receiver: HMAC check on the raw body, a fast 200, then a re-read of the order from the GraphQL Admin API instead of trusting the payload.
  • An hourly workflow with two branches: a reconciliation resuming from a stored checkpoint, and a watchdog that re-creates the subscription if it vanished.

Both were run on n8n 2.46.6 against a mock GraphQL endpoint and PostgreSQL 16, not a live shop. API version: 2026-10, the latest stable at the time of writing.

Do you need any of this? TOML versus API

Shopify's own advice: "Choose app-specific subscriptions unless your topics, delivery URIs, or filters need to vary between shops." Per its subscription docs, failing app-specific subscriptions "will not be deleted by Shopify"; failing shop-specific ones "will be deleted".

[webhooks]
api_version = "2026-10"

[[webhooks.subscriptions]]
topics = ["orders/updated"]
uri = "https://YOUR_N8N_HOST/webhook/shopify/orders-updated"
Enter fullscreen mode Exit fullscreen mode

That block goes in shopify.app.toml and ships with shopify app deploy (syntax from Shopify's docs; not deployed in the test run).

My default: use it whenever there is an app project and one URL serves every shop. The watchdog below is then pointless, since webhookSubscriptions "returns only shop-scoped subscriptions, not app-scoped subscriptions configured in TOML files".

Stay with the API when the URL differs per shop or there is no app project. The reconciliation job is worth having either way: deliveries can still be missed.

What Shopify promises

From the webhooks overview, the HTTPS delivery page and ignoring duplicates:

Topic What to know
Timeouts One second to connect, five for the whole request; anything outside the 200 range is an error.
Retries 8 retries over 4 hours, then deletion (API-created subscriptions). Warning emails go to the app's emergency developer address.
Ordering No guarantee. Sort with X-Shopify-Triggered-At or the payload's updated_at.
Duplicates They happen. Deduplicate on X-Shopify-Webhook-Id; X-Shopify-Event-Id only correlates deliveries from one merchant action.
Reconciliation Recommended: fetch objects updated "since the last time the job ran".

Keep the webhooks and add one cheap poll an hour as a safety net.


The webhook is a doorbell, not the parcel. Take the order ID from it and ask Shopify for the current state: out-of-order deliveries mostly stop mattering, and both paths feed the same upsert. The price is one API call per event; on a Standard plan the GraphQL budget is 100 points per second.

Subscribe, and authenticate in 2026

Create the subscription

mutation CreateOrdersUpdated($sub: WebhookSubscriptionInput!) {
  webhookSubscriptionCreate(topic: ORDERS_UPDATED, webhookSubscription: $sub) {
    webhookSubscription { id topic uri }
    userErrors { field message }
  }
}
Enter fullscreen mode Exit fullscreen mode
{ "sub": { "uri": "https://YOUR_N8N_HOST/webhook/shopify/orders-updated", "format": "JSON" } }
Enter fullscreen mode Exit fullscreen mode

POST it to https://YOUR_SHOP.myshopify.com/admin/api/2026-10/graphql.json (callbackUrl is deprecated, use uri). Use the production URL: n8n registers it when the workflow is published.

Get a token

Tokens changed in 2026. New custom apps can't be created in the admin any more (existing ones keep working); they come from the Dev Dashboard. A token from the client credentials grant lives 86,399 seconds, about a day, and only works for apps your organization owns.

A static header credential would break after a day, so the workflows fetch a token first: an HTTP Request node posts to /admin/oauth/access_token with a Custom Auth credential, then the GraphQL node's Headers option sends X-Shopify-Access-Token. The credential's JSON makes the request a form, as Shopify requires, and keeps the secret out of the workflow:

{
  "headers": { "Content-Type": "application/x-www-form-urlencoded" },
  "body": {
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }
}
Enter fullscreen mode Exit fullscreen mode

Without the Content-Type header, n8n 2.46.6 sent the same body as JSON; with it, the mock received the three fields form-encoded. With a non-expiring token (older admin-created app), drop the token node and use a Header Auth credential.

The HMAC key is the app's client secret, kept in a Crypto credential.

Workflow 1: the receiver

  1. Webhook: POST, path shopify/orders-updated, Respond: Using 'Respond to Webhook' Node, option Raw Body on.
  2. Crypto: Hmac, Binary File on, property data, SHA256, output computed_hmac, BASE64.
  3. IF: computed_hmac equals the x-shopify-hmac-sha256 header (node headers are lower-cased).
  4. Respond to Webhook: No Data, 200 on true; 401 on false, followed by a Stop and Error node.
  5. HTTP Request (token), then GraphQL (order by ID), then an IF on order being null, Edit Fields, and the Postgres upsert.

The expressions used in the IF and GraphQL nodes:

{{ $json.computed_hmac }}  equals  {{ $json.headers['x-shopify-hmac-sha256'] }}
variables: {{ { "id": $('Shopify webhook').item.json.body.admin_graphql_api_id } }}
Enter fullscreen mode Exit fullscreen mode

The order query:

query OrderById($id: ID!) {
  order(id: $id) {
    id name updatedAt displayFinancialStatus displayFulfillmentStatus
    currentTotalPriceSet { shopMoney { amount currencyCode } }
  }
}
Enter fullscreen mode Exit fullscreen mode

Why it is built this way

  • Raw Body. The HMAC covers the exact bytes Shopify sent; re-serialised JSON won't match. With Raw Body on, the bytes arrive in a binary property that the Crypto node hashes directly.
  • 200 before the work. The Respond node sits before the token and GraphQL calls, so Shopify's clock stops there. If the fetch fails, the reconciliation picks the order up.
  • Stop and Error after the 401. If the client secret is wrong or mistyped, every real delivery fails the HMAC check. Shopify counts those 401s as failures, but without this node n8n shows them as successful executions. With it they fail and your Error Workflow fires (so does a forged request: rate-limit that alert). The IF is not a constant-time comparison; I consider that acceptable for a base64 HMAC over the internet, but do the check in a reverse proxy if you disagree.
  • order: null. A deleted order, or one outside the default 60-day reach, comes back as null. The IF skips it instead of failing on data.order.id.
  • GraphQL node, not HTTP Request. Shopify can answer HTTP 200 with the error in errors, for unapproved protected data for instance. A mock doing that passed through the HTTP Request node as a normal item, while the GraphQL node failed. Don't set it to Continue (using error output): the error body then leaves on both outputs.

Workflow 2: reconciliation and watchdog

Two Schedule Triggers, so a failure in one branch can't stop the other.

Reconciliation with a checkpoint

Shopify's docs say to fetch objects updated "since the last time the job ran", so the run state is stored in a sync_state table, read and written by Postgres nodes. The first node computes the lower bound and this run's start, once:

SELECT
  to_char((COALESCE((SELECT last_started_at FROM sync_state WHERE job = 'orders_reconciliation'),
                    now() - interval '24 hours') - interval '1 hour') AT TIME ZONE 'UTC',
          'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS since,
  to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD"T"HH24:MI:SS"Z"') AS run_started_at;
Enter fullscreen mode Exit fullscreen mode

Every page of a run uses the same filter, because the GraphQL node reads since from that node (a $now-based expression had drifted by a second between pages):

{{ { "q": "updated_at:>='" + $('Read last sync point').first().json.since + "'", "cursor": $json.data?.orders?.pageInfo?.endCursor ?? null } }}
Enter fullscreen mode Exit fullscreen mode
query RecentOrders($q: String!, $cursor: String) {
  orders(first: 100, after: $cursor, query: $q, sortKey: UPDATED_AT) {
    nodes { id name updatedAt displayFinancialStatus displayFulfillmentStatus
            currentTotalPriceSet { shopMoney { amount currencyCode } } }
    pageInfo { hasNextPage endCursor }
  }
}
Enter fullscreen mode Exit fullscreen mode

One Postgres node upserts the whole page in a single statement, then an Edit Fields node puts the GraphQL response back (Postgres returns its own result, not the page), and an IF on hasNextPage loops back into the GraphQL node. On the last page the IF's false output runs Save sync point.

The page upsert:

INSERT INTO shopify_orders (gid, name, financial_status, fulfillment_status, total, currency, updated_at)
SELECT t.id, t.name, t."displayFinancialStatus", t."displayFulfillmentStatus",
       (t."currentTotalPriceSet"->'shopMoney'->>'amount')::numeric,
       t."currentTotalPriceSet"->'shopMoney'->>'currencyCode',
       t."updatedAt"
FROM jsonb_to_recordset($1::jsonb) AS t(
  id text, name text, "updatedAt" timestamptz,
  "displayFinancialStatus" text, "displayFulfillmentStatus" text,
  "currentTotalPriceSet" jsonb)
ON CONFLICT (gid) DO UPDATE SET
  name = EXCLUDED.name, financial_status = EXCLUDED.financial_status,
  fulfillment_status = EXCLUDED.fulfillment_status, total = EXCLUDED.total,
  currency = EXCLUDED.currency, updated_at = EXCLUDED.updated_at
WHERE shopify_orders.updated_at <= EXCLUDED.updated_at;
Enter fullscreen mode Exit fullscreen mode

The parameter and the Edit Fields value:

Query Parameters:  {{ [ JSON.stringify($json.data.orders.nodes) ] }}
Edit Fields (JSON): {{ $('Orders updated since the last sync').first().json }}
Enter fullscreen mode Exit fullscreen mode

The checkpoint:

INSERT INTO sync_state (job, last_started_at) VALUES ('orders_reconciliation', $1::timestamptz)
ON CONFLICT (job) DO UPDATE SET last_started_at = EXCLUDED.last_started_at;
Enter fullscreen mode Exit fullscreen mode

Why one chain. The obvious design splits each page into a per-order upsert branch and a "Another page?" branch feeding Save, but with n8n's v1 execution order the branches leaving a node run top to bottom by canvas position, so moving nodes around could run Save despite a failed upsert. Here Save sync point has a single input, the IF's false output, and the IF only receives an item after Upsert page succeeded, wherever the nodes sit. One statement per page is also atomic, and an empty page still emits an item (jsonb_to_recordset on [] inserts nothing), so the checkpoint moves.

In the test run:

  • Failure. Postgres was made to reject one order with a CHECK constraint, once on the second page and once on the first. The execution failed at Upsert page and sync_state kept its old value; with the constraint removed, the next run started again from it. The test was repeated with the chain laid out in reverse order on the canvas: same result in all four cases.
  • Gaps. After a simulated six-hour gap, the next run asked for everything since seven hours ago, which is what an outage long enough to delete a subscription needs. An empty page still saved the checkpoint.
  • Overlap. The one-hour look-back absorbs clock skew and search-index lag; the upsert makes the repeats harmless, and a row already newer in the database is not overwritten.

Don't use max(updated_at) of your orders table as the checkpoint: the webhook path writes there too, and one live delivery after an outage would move it past the hole.

Watchdog

query SubscriptionCheck($uri: String!) {
  webhookSubscriptions(first: 10, topics: [ORDERS_UPDATED], uri: $uri) {
    nodes { id topic uri }
  }
}
Enter fullscreen mode Exit fullscreen mode

If nodes.length is 0, the CreateOrdersUpdated mutation runs and the alert includes its userErrors, so you can tell "re-created" from "tried and failed". The first test run created the subscription and alerted; the second did nothing.

The watchdog runs on the instance it watches, so it can't notice that instance dying. Poll /healthz from an external monitor, and make sure someone reads the emergency developer mailbox.

The tables

SQL for shopify_orders and sync_state
CREATE TABLE shopify_orders (
  gid text PRIMARY KEY, name text NOT NULL, financial_status text,
  fulfillment_status text NOT NULL, total numeric(12,2) NOT NULL,
  currency char(3) NOT NULL, updated_at timestamptz NOT NULL
);
CREATE TABLE sync_state (job text PRIMARY KEY, last_started_at timestamptz NOT NULL);
Enter fullscreen mode Exit fullscreen mode

The receiver runs the same INSERT ... ON CONFLICT (gid) DO UPDATE ... WHERE shopify_orders.updated_at <= EXCLUDED.updated_at with a VALUES ($1, ... $7) list, fed by an array expression ({{ [ $json.id, $json.name, ... ] }}) rather than a comma-separated string, so a comma in a value can't shift columns. The WHERE guard refuses older data when two executions for the same order finish out of order.

Self-hosting notes

  • Shopify must reach the webhook, nobody else the editor. Cloudflare Access in front of the editor with a Bypass policy on /webhook does both. My write-up of that setup, with the rest of a small VPS stack: self-hosting n8n on a French VPS (in French).
  • Behind a reverse proxy, set the public URL: N8N_WEBHOOK_URL, plus N8N_PROXY_HOPS=1, per n8n's docs.
  • The token ends up in the execution history. After the test runs, the 24-hour token was found in every stored execution that fetched one (the client secret in none, since it stays in the credential). Turn off Save successful production executions for the receiver, or set EXECUTIONS_DATA_SAVE_ON_SUCCESS=none and a short EXECUTIONS_DATA_MAX_AGE (docs); failed executions keep it too.
  • The client secret lives in two credentials, Crypto (HMAC key) and Custom Auth (token request). Rotate both: miss the Custom Auth one and token calls fail; miss the Crypto one and every real webhook gets a 401, which Stop and Error makes visible.
  • A restart of a few seconds is covered by Shopify's retries. A stuck container is covered by the checkpoint (the data) and the watchdog (the subscription).

What this doesn't solve

  • Write-back loops. If the upsert step edits the order in Shopify (tags, metafields), Shopify emits another orders/updated. Mark your own writes and skip them.
  • Token caching. The receiver requests a token per event. No documented limit on the token endpoint turned up, so it's unclear where that stops being fine; at volume, cache the token (it lives 24 hours) in a table or an n8n Data Table.
  • A live shop. Everything ran against mocks and a temporary Postgres. The updated_at:>='...' filter follows Shopify's documented syntax but wasn't run on real orders; try it on a development store.

Test the receiver without a shop

BODY='{"admin_graphql_api_id":"gid://shopify/Order/42","updated_at":"2026-11-05T10:00:00-05:00"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac 'YOUR_CLIENT_SECRET' -binary | base64)
curl -s -o /dev/null -w "%{http_code}\n" -X POST -H 'content-type: application/json' \
  -H "X-Shopify-Hmac-Sha256: $SIG" --data-binary "$BODY" \
  https://YOUR_N8N_HOST/webhook/shopify/orders-updated
Enter fullscreen mode Exit fullscreen mode

Expected: 200 for a valid signature, 401 for another secret, a changed body or a missing header.

Your turn


How would you notice today that an API-created subscription had disappeared: alerting on silence, a scheduled re-check like this one, or just moving to TOML? Tell me what the design above misses.

I'm Thomas, a freelance integrator (Shopify, HubSpot, n8n) based near Bordeaux. I work under the Cinfolog brand

Drafted with AI assistance. I reviewed it and stand by every claim; corrections welcome in the comments.

Top comments (1)

Collapse
 
krusenas profile image
Karolis •

In the hourly reconciliation job, save the checkpoint after the upsert succeeds. If you save it before the upsert and the run dies, you skip that page. If you save after, a crash just replays the page and the upsert's idempotency check absorbs the repeat. I built Webhook Relay, it stores failed deliveries and retries them.