Architecture
What is inside each JSON file: the shared webhook front, the nodes of every workflow, the HTTP calls they make, the HubSpot properties they rely on, and the decisions behind them.
The shared front of workflows 01, 02, 03 and 03b
Shopify signs the raw body of each webhook with HMAC-SHA256 and sends the base64 result in the X-Shopify-Hmac-Sha256 header. The four webhook workflows start with the same four nodes and then split:
Webhook (POST, Raw Body on)
-> Crypto: HMAC SHA256 over binary property "data", base64 -> calculatedHmac
-> IF, all of:
calculatedHmac == header x-shopify-hmac-sha256
header x-shopify-shop-domain == YOUR_SHOP.myshopify.com
header x-shopify-topic: "customers/..." (01) or "orders/paid" (02, 03, 03b)
true -> Respond to Webhook 200 (no body) -> business nodes
false -> Respond to Webhook 401 ("Signature invalide"), end
- Raw Body makes n8n expose the exact bytes received, as the binary property
data. A signature computed over re-serialised JSON would not match. - The Crypto node, version 2, reads the secret from a credential instead of a node field. That is the reason for the minimum n8n version of 2.7.
- The shop domain is a literal in the IF node. Until you replace
YOUR_SHOP.myshopify.com, every request is rejected: the workflows fail closed. - The comparison is a plain string equality. n8n has no native constant-time comparison node and the kit does not add a Code node to get one.
Decisions, with their cost
- D1. Generic Webhook + Crypto, not the Shopify Trigger node
- In the n8n 2.46.6 source, ShopifyTrigger.node.ts answers immediately and ignores a badly signed request (it returns an empty object) instead of rejecting it. It passes on only the body, so the headers, including
X-Shopify-Webhook-Id, are lost. GenericFunctions.ts pins the REST Admin API at2024-07. Cost: you create the Shopify webhooks yourself and keep three header comparisons up to date. - D2. HTTP Request on date-versioned HubSpot endpoints, not the HubSpot node
- The HubSpot node of n8n 2.46.6 (HubspotV2.node.ts) still calls
/contacts/v1/,/deals/v1/,/companies/v2/and/crm/v3/paths. HubSpot’s changelog marks the v1 to v3 API families as unsupported, with migration due before September 2027. The workflows call/crm/objects/2026-09/.... Cost: request bodies are built by hand in expressions. - D3. Upsert on a key, no search before write
- Asking HubSpot “does it exist?” and then creating leaves a window: two close deliveries both get “no”. Contacts are upserted on
email, deals on the unique propertyshopify_order_id. Cost: unique-value properties must be created as such (workflow 00), because the setting cannot be changed afterwards. - D4. Respond first, work after
- Shopify waits five seconds in total and retries eight times over four hours. The workflows answer
200as soon as the signature checks out. Cost: once the200is sent, Shopify considers the delivery done. If HubSpot then fails, Shopify will not retry; workflow 04 tells you, and replaying is up to you. - D5. Errors that are not HTTP errors are turned into errors
- A HubSpot batch can answer
207withnumErrorsabove zero, and a Shopify GraphQL call can answer200with anerrorsarray. Both are 2xx, so n8n would call the node a success. An IF node tests for them and a Stop and Error node fails the run. - D6. A new Shopify token on every run (workflow 03)
- Tokens from the client credentials grant expire after about 24 hours. That grant is open only to an app built by your own organization and installed on a store you own (see the requirements). Storing one without a Code node means adding a data store and expiry logic, so workflow 03 requests a token on every execution. Cost: one extra call per paid order, and the token appears in kept failed executions. Workflow 03b takes a fixed token from a Header Auth credential for older apps.
- D7. In workflow 02, the deal does not depend on the contact
- The contact upsert has
onError: continueRegularOutputand no retry. The deal upsert runs anyway. The association is attempted only if the contact call returned an id; otherwise the run stops with “deal created but not associated”. Cost: a429on the contact call is not retried either; you associate by hand. - D8. Successful executions are not kept
- The workflows set
saveDataSuccessExecution: noneandsaveDataErrorExecution: all. Failed runs keep the webhook body, so they contain customer data. See the retention variables on the setup page.
Nodes of each workflow
Names are given as stored in the file, then in English. HubSpot calls its sales records “deals”; the French node names say “transaction”, which is the label of the French HubSpot interface.
00 — Create the HubSpot properties
Manual trigger -> HubSpot: create contact properties -> HubSpot: create deal properties
| # | Node (name in the file / English) | Type | What it does |
|---|---|---|---|
| 1 | Lancer à la mainRun manually | Manual Trigger v1 | run once from the editor |
| 2 | HubSpot : créer les propriétés de contactHubSpot: create contact properties | HTTP Request v4.2 | POST api.hubapi.com/crm/properties/2026-09/contacts/batch/create; HubSpot App Token credential; retry on fail: 3 tries, 2000 ms apart; on error: continueRegularOutput |
| 3 | HubSpot : créer les propriétés de transactionHubSpot: create deal properties | HTTP Request v4.2 | POST api.hubapi.com/crm/properties/2026-09/deals/batch/create; HubSpot App Token credential; retry on fail: 3 tries, 2000 ms apart; on error: continueRegularOutput |
01 — Customer to contact
Webhook -> HMAC -> Valid? --yes-> Respond 200 -> Email present? --yes-> Prepare contact -> HubSpot upsert -> Errors? --yes-> Stop and Error
\-no--> Respond 401 \-no--> Ignored
| # | Node (name in the file / English) | Type | What it does |
|---|---|---|---|
| 1 | Webhook Shopify : client créé ou modifiéWebhook: customer created or updated | Webhook v2.1 | POST /webhook/shopify-client; Raw Body on; answers through Respond to Webhook |
| 2 | Calculer la signature HMACCompute HMAC signature | Crypto v2 | HMAC, SHA256, base64, binary property data into calculatedHmac; secret from a Crypto credential |
| 3 | Signature et boutique valides ?Valid signature and shop? | IF v2.2 | all true: $json.calculatedHmac == $json.headers['x-shopify-hmac-sha256'] & $json.headers['x-shopify-shop-domain'] == 'YOUR_SHOP.myshopify.com' & $json.headers['x-shopify-topic'] starts with 'customers/' |
| 4 | Répondre 200 à ShopifyRespond 200 to Shopify | Respond to Webhook v1.4 | HTTP 200, no body |
| 5 | Répondre 401Respond 401 | Respond to Webhook v1.4 | HTTP 401, body Signature invalide |
| 6 | E-mail présent ?Email present? | IF v2.2 | all true: $json.body.email is not empty |
| 7 | Ignoré : client sans e-mailIgnored: customer without email | No Operation v1 | end of branch |
| 8 | Préparer le contactPrepare contact | Edit Fields (Set) v3.4 | sets email, properties |
| 9 | HubSpot : créer ou mettre à jour le contactHubSpot: upsert contact | HTTP Request v4.2 | POST api.hubapi.com/crm/objects/2026-09/contacts/batch/upsert; HubSpot App Token credential; retry on fail: 3 tries, 2000 ms apart |
| 10 | HubSpot a-t-il signalé des erreurs ?Did HubSpot report errors? | IF v2.2 | all true: ($json.numErrors ?? 0) > 0 |
| 11 | Arrêt : erreur renvoyée par HubSpotStop: error returned by HubSpot | Stop and Error v1 | fails the execution with a message (triggers the error workflow) |
02 — Paid order to deal
Webhook -> HMAC -> Valid? --yes-> Respond 200 -> Usable order? --yes-> Deal settings -> Prepare
\-no--> Respond 401 \-no--> Ignored
Prepare -> Upsert contact -> Upsert deal -> Deal error? --yes-> Stop and Error
\-no--> Contact id available? --yes-> Associate deal with contact
\-no--> Stop and Error (not associated)
| # | Node (name in the file / English) | Type | What it does |
|---|---|---|---|
| 1 | Webhook Shopify : commande payéeWebhook: order paid | Webhook v2.1 | POST /webhook/shopify-commande-payee; Raw Body on; answers through Respond to Webhook |
| 2 | Calculer la signature HMACCompute HMAC signature | Crypto v2 | HMAC, SHA256, base64, binary property data into calculatedHmac; secret from a Crypto credential |
| 3 | Signature et boutique valides ?Valid signature and shop? | IF v2.2 | all true: $json.calculatedHmac == $json.headers['x-shopify-hmac-sha256'] & $json.headers['x-shopify-shop-domain'] == 'YOUR_SHOP.myshopify.com' & $json.headers['x-shopify-topic'] == 'orders/paid' |
| 4 | Répondre 200 à ShopifyRespond 200 to Shopify | Respond to Webhook v1.4 | HTTP 200, no body |
| 5 | Répondre 401Respond 401 | Respond to Webhook v1.4 | HTTP 401, body Signature invalide |
| 6 | Commande exploitable ?Usable order? | IF v2.2 | all true: String($json.body.test) != 'true' & $json.body.email || $json.body.contact_email || $json.body.customer?.email || '' is not empty |
| 7 | Ignorée : commande de test ou sans e-mailIgnored: test order or no email | No Operation v1 | end of branch |
| 8 | Réglages de la transactionDeal settings | Edit Fields (Set) v3.4 | sets hubspot_pipeline, hubspot_dealstage; keeps other fields |
| 9 | Préparer contact et transactionPrepare contact and deal | Edit Fields (Set) v3.4 | sets email, orderId, contactProperties, dealProperties; keeps other fields |
| 10 | HubSpot : créer ou mettre à jour le contactHubSpot: upsert contact | HTTP Request v4.2 | POST api.hubapi.com/crm/objects/2026-09/contacts/batch/upsert; HubSpot App Token credential; on error: continueRegularOutput |
| 11 | HubSpot : créer ou mettre à jour la transactionHubSpot: upsert deal | HTTP Request v4.2 | POST api.hubapi.com/crm/objects/2026-09/0-3/batch/upsert; HubSpot App Token credential; retry on fail: 3 tries, 2000 ms apart |
| 12 | Erreur HubSpot sur la transaction ?HubSpot error on the deal? | IF v2.2 | all true: ($json.numErrors ?? 0) > 0 |
| 13 | Contact disponible pour l'association ?Contact available for association? | IF v2.2 | all true: $('HubSpot : créer ou mettre à jour le contact').item.json.results?.[0]?.id ?? '' is not empty |
| 14 | HubSpot : associer la transaction au contactHubSpot: associate deal with contact | HTTP Request v4.2 | PUT api.hubapi.com/crm/objects/2026-09/deal/{id}/associations/default/contact/{id}; HubSpot App Token credential; retry on fail: 3 tries, 2000 ms apart |
| 15 | Arrêt : erreur renvoyée par HubSpotStop: error returned by HubSpot | Stop and Error v1 | fails the execution with a message (triggers the error workflow) |
| 16 | Arrêt : transaction créée mais non associéeStop: deal created but not associated | Stop and Error v1 | fails the execution with a message (triggers the error workflow) |
03 — Customer segmentation (token on every run)
Webhook -> HMAC -> Valid? --yes-> Respond 200 -> Linked to a customer? --yes-> Settings -> Get token -> GraphQL read
\-no--> Respond 401 \-no--> Ignored
GraphQL read -> Customer found? --yes-> Prepare properties -> HubSpot update -> Errors? --yes-> Stop and Error
\-no--> Stop and Error
The GraphQL query reads customer(id) with numberOfOrders, amountSpent, lastOrder and defaultEmailAddress. It does not use Customer.email or Customer.emailMarketingConsent, which Shopify’s documentation marks as deprecated. Values are re-read from Shopify on every event, never incremented, so a replay changes nothing.
| # | Node (name in the file / English) | Type | What it does |
|---|---|---|---|
| 1 | Webhook Shopify : commande payée (segmentation)Webhook: order paid (segmentation) | Webhook v2.1 | POST /webhook/shopify-segmentation; Raw Body on; answers through Respond to Webhook |
| 2 | Calculer la signature HMACCompute HMAC signature | Crypto v2 | HMAC, SHA256, base64, binary property data into calculatedHmac; secret from a Crypto credential |
| 3 | Signature et boutique valides ?Valid signature and shop? | IF v2.2 | all true: $json.calculatedHmac == $json.headers['x-shopify-hmac-sha256'] & $json.headers['x-shopify-shop-domain'] == 'YOUR_SHOP.myshopify.com' & $json.headers['x-shopify-topic'] == 'orders/paid' |
| 4 | Répondre 200 à ShopifyRespond 200 to Shopify | Respond to Webhook v1.4 | HTTP 200, no body |
| 5 | Répondre 401Respond 401 | Respond to Webhook v1.4 | HTTP 401, body Signature invalide |
| 6 | Commande rattachée à un client ?Order linked to a customer? | IF v2.2 | all true: String($json.body.test) != 'true' & String($json.body.customer?.id ?? '') is not empty |
| 7 | Ignorée : commande de test ou sans clientIgnored: test order or no customer | No Operation v1 | end of branch |
| 8 | Réglages de segmentationSegmentation settings | Edit Fields (Set) v3.4 | sets seuil_recurrent, seuil_fidele; keeps other fields |
| 9 | Shopify : obtenir un jeton (client credentials)Shopify: get a token (client credentials) | HTTP Request v4.2 | POST YOUR_SHOP.myshopify.com/admin/oauth/access_token; credential type httpCustomAuth; retry on fail: 3 tries, 2000 ms apart |
| 10 | Shopify GraphQL : lire le clientShopify GraphQL: read the customer | HTTP Request v4.2 | POST YOUR_SHOP.myshopify.com/admin/api/2026-10/graphql.json; retry on fail: 3 tries, 2000 ms apart |
| 11 | Client trouvé dans la réponse ?Customer found in the response? | IF v2.2 | all true: $json.data?.customer?.id ?? '' is not empty |
| 12 | Arrêt : client introuvable ou accès refuséStop: customer not found or access denied | Stop and Error v1 | fails the execution with a message (triggers the error workflow) |
| 13 | Préparer les propriétés de segmentationPrepare segmentation properties | Edit Fields (Set) v3.4 | sets email, properties |
| 14 | HubSpot : mettre à jour le contactHubSpot: update contact | HTTP Request v4.2 | POST api.hubapi.com/crm/objects/2026-09/contacts/batch/upsert; HubSpot App Token credential; retry on fail: 3 tries, 2000 ms apart |
| 15 | HubSpot a-t-il signalé des erreurs ?Did HubSpot report errors? | IF v2.2 | all true: ($json.numErrors ?? 0) > 0 |
| 16 | Arrêt : erreur renvoyée par HubSpotStop: error returned by HubSpot | Stop and Error v1 | fails the execution with a message (triggers the error workflow) |
03b — Same, with a fixed token
Identical to 03 without the “get a token” node. The GraphQL node authenticates with a Header Auth credential carrying X-Shopify-Access-Token.
| # | Node (name in the file / English) | Type | What it does |
|---|---|---|---|
| 1 | Webhook Shopify : commande payée (segmentation)Webhook: order paid (segmentation) | Webhook v2.1 | POST /webhook/shopify-segmentation; Raw Body on; answers through Respond to Webhook |
| 2 | Calculer la signature HMACCompute HMAC signature | Crypto v2 | HMAC, SHA256, base64, binary property data into calculatedHmac; secret from a Crypto credential |
| 3 | Signature et boutique valides ?Valid signature and shop? | IF v2.2 | all true: $json.calculatedHmac == $json.headers['x-shopify-hmac-sha256'] & $json.headers['x-shopify-shop-domain'] == 'YOUR_SHOP.myshopify.com' & $json.headers['x-shopify-topic'] == 'orders/paid' |
| 4 | Répondre 200 à ShopifyRespond 200 to Shopify | Respond to Webhook v1.4 | HTTP 200, no body |
| 5 | Répondre 401Respond 401 | Respond to Webhook v1.4 | HTTP 401, body Signature invalide |
| 6 | Commande rattachée à un client ?Order linked to a customer? | IF v2.2 | all true: String($json.body.test) != 'true' & String($json.body.customer?.id ?? '') is not empty |
| 7 | Ignorée : commande de test ou sans clientIgnored: test order or no customer | No Operation v1 | end of branch |
| 8 | Réglages de segmentationSegmentation settings | Edit Fields (Set) v3.4 | sets seuil_recurrent, seuil_fidele; keeps other fields |
| 9 | Shopify GraphQL : lire le clientShopify GraphQL: read the customer | HTTP Request v4.2 | POST YOUR_SHOP.myshopify.com/admin/api/2026-10/graphql.json; credential type httpHeaderAuth; retry on fail: 3 tries, 2000 ms apart |
| 10 | Client trouvé dans la réponse ?Customer found in the response? | IF v2.2 | all true: $json.data?.customer?.id ?? '' is not empty |
| 11 | Arrêt : client introuvable ou accès refuséStop: customer not found or access denied | Stop and Error v1 | fails the execution with a message (triggers the error workflow) |
| 12 | Préparer les propriétés de segmentationPrepare segmentation properties | Edit Fields (Set) v3.4 | sets email, properties |
| 13 | HubSpot : mettre à jour le contactHubSpot: update contact | HTTP Request v4.2 | POST api.hubapi.com/crm/objects/2026-09/contacts/batch/upsert; HubSpot App Token credential; retry on fail: 3 tries, 2000 ms apart |
| 14 | HubSpot a-t-il signalé des erreurs ?Did HubSpot report errors? | IF v2.2 | all true: ($json.numErrors ?? 0) > 0 |
| 15 | Arrêt : erreur renvoyée par HubSpotStop: error returned by HubSpot | Stop and Error v1 | fails the execution with a message (triggers the error workflow) |
04 — Failure alert
Error Trigger -> Send Email (SMTP)
| # | Node (name in the file / English) | Type | What it does |
|---|---|---|---|
| 1 | Erreur dans un workflowError in a workflow | Error Trigger v1 | receives the failed workflow name, node, message and execution URL |
| 2 | Envoyer l'alerte par e-mailSend the alert email | Send Email v2.1 | SMTP credential; appendAttribution off |
HTTP calls
| WF | Node | Method | URL (host and path) | Retry | On error |
|---|---|---|---|---|---|
00 | HubSpot: create contact properties | POST | api.hubapi.com/crm/properties/2026-09/contacts/batch/create | 3x / 2000 ms | continue |
00 | HubSpot: create deal properties | POST | api.hubapi.com/crm/properties/2026-09/deals/batch/create | 3x / 2000 ms | continue |
01 | HubSpot: upsert contact | POST | api.hubapi.com/crm/objects/2026-09/contacts/batch/upsert | 3x / 2000 ms | stop |
02 | HubSpot: upsert contact | POST | api.hubapi.com/crm/objects/2026-09/contacts/batch/upsert | none | continue |
02 | HubSpot: upsert deal | POST | api.hubapi.com/crm/objects/2026-09/0-3/batch/upsert | 3x / 2000 ms | stop |
02 | HubSpot: associate deal with contact | PUT | api.hubapi.com/crm/objects/2026-09/deal/{id}/associations/default/contact/{id} | 3x / 2000 ms | stop |
03 | Shopify: get a token (client credentials) | POST | YOUR_SHOP.myshopify.com/admin/oauth/access_token | 3x / 2000 ms | stop |
03 | Shopify GraphQL: read the customer | POST | YOUR_SHOP.myshopify.com/admin/api/2026-10/graphql.json | 3x / 2000 ms | stop |
03 | HubSpot: update contact | POST | api.hubapi.com/crm/objects/2026-09/contacts/batch/upsert | 3x / 2000 ms | stop |
03b | Shopify GraphQL: read the customer | POST | YOUR_SHOP.myshopify.com/admin/api/2026-10/graphql.json | 3x / 2000 ms | stop |
03b | HubSpot: update contact | POST | api.hubapi.com/crm/objects/2026-09/contacts/batch/upsert | 3x / 2000 ms | stop |
All nodes with retry use the same setting. Credentials are never stored in the node: HubSpot calls use a HubSpot App Token credential (a service key goes in that field), the Shopify token call uses a Custom Auth credential.
HubSpot properties created by workflow 00
| Name | Object | Type | Unique | Group |
|---|---|---|---|---|
shopify_customer_id | contact | string/text | yes | contactinformation |
shopify_orders_count | contact | number | contactinformation | |
shopify_total_spent | contact | number | contactinformation | |
shopify_last_order_date | contact | datetime/date | contactinformation | |
shopify_segment | contact | enumeration/select | contactinformation | |
shopify_email_marketing_state | contact | string/text | contactinformation | |
shopify_order_id | deal | string/text | yes | dealinformation |
shopify_order_name | deal | string/text | dealinformation |
The two unique properties count against HubSpot’s cap of ten unique-value properties per object. shopify_segment takes the internal values nouveau, recurrent and fidele.
What happens when something fails
| Event | Result | Who finds out |
|---|---|---|
| Wrong signature, wrong shop domain (including an unreplaced placeholder) or wrong topic | HTTP 401, nothing else runs. The run itself ends normally. | Nobody by email. Shopify sees the 401. |
| HubSpot answers 207 with errors | Stop and Error after the upsert. | Workflow 04 email. |
| HubSpot answers 4xx or 5xx on a node with retry | Three tries, two seconds apart, then the run fails. | Workflow 04 email. |
| HubSpot rejects the contact in workflow 02 | Deal still upserted, association skipped, run stops with “deal created but not associated”. | Workflow 04 email. |
Shopify GraphQL answers 200 with errors (workflow 03) | “Customer found?” is false, run stops with Shopify’s message. | Workflow 04 email. |
| n8n unreachable, or the workflow not published | Shopify gets an error or no answer, retries, and can delete a webhook created in the admin after repeated failures. | Nobody. No run exists, so no alert. |
The last row is the case an error workflow cannot cover. It is the reason to look at your webhook list now and then, and to keep a periodic catch-up on flows that matter: why a webhook still needs a daily catch-up (in French).