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).
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"
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.
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 }
}
}
{ "sub": { "uri": "https://YOUR_N8N_HOST/webhook/shopify/orders-updated", "format": "JSON" } }
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"
}
}
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
-
Webhook: POST, path
shopify/orders-updated, Respond: Using 'Respond to Webhook' Node, option Raw Body on. -
Crypto: Hmac, Binary File on, property
data, SHA256, outputcomputed_hmac, BASE64. -
IF:
computed_hmacequals thex-shopify-hmac-sha256header (node headers are lower-cased). - Respond to Webhook: No Data, 200 on true; 401 on false, followed by a Stop and Error node.
-
HTTP Request (token), then GraphQL (order by ID), then an IF on
orderbeing 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 } }}
The order query:
query OrderById($id: ID!) {
order(id: $id) {
id name updatedAt displayFinancialStatus displayFulfillmentStatus
currentTotalPriceSet { shopMoney { amount currencyCode } }
}
}
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 asnull. The IF skips it instead of failing ondata.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;
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 } }}
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 }
}
}
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;
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 }}
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;
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
CHECKconstraint, once on the second page and once on the first. The execution failed at Upsert page andsync_statekept 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 }
}
}
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
/healthzfrom 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);
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
/webhookdoes 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, plusN8N_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=noneand a shortEXECUTIONS_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
Expected: 200 for a valid signature, 401 for another secret, a changed body or a missing header.
Your turn
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)
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.