Setup reference
Everything you have to change or provide before the first run: instance requirements, credentials, placeholders, values you may tune, and the Shopify webhooks.
Requirements
- n8n 2.7 or later. Tested on 2.46.6, which needs Node.js 24 when self-hosted. Cloud or self-hosted both work; the instance must be reachable from the Internet over HTTPS to receive webhooks.
- HubSpot: access to contacts and deals, and a service key. HubSpot disabled the creation of new legacy private apps (28 September 2026 for new accounts, 26 October 2026 for existing ones), so the kit does not use them. Service keys were in public beta at the date of verification. The menu path differs between HubSpot’s developer documentation (Development > Keys > Service keys) and n8n’s credential page (Settings > Account Management > Integrations > Service Keys): check on screen.
- Shopify: permission to create webhooks in the store admin. Workflow 03 uses Shopify’s client credentials grant, which Shopify reserves for apps developed by your own organization and installed on stores you own; public and custom apps cannot use it. Create the app in the Dev Dashboard with
read_customersandread_orders, and put its client ID and secret in the Custom Auth credential below. With an older custom app token (shpat_), use workflow 03b.
Credentials
The files hold no secret. Each node references a credential by name and type. Create them before importing, with exactly these names and types: on import, n8n links each node to the credential of the same name and type. If you imported first, select the credential in every node, or delete the imported copies and import again, before publishing; otherwise every request, signed or not, gets a 400.
| Name | n8n type | Content | Used by |
|---|---|---|---|
HubSpot - Service Key | HubSpot App Token | The service key, in the App Token field | 00, 01, 02, 03, 03b |
Shopify - secret de signature des webhooks | Crypto | Hmac Secret: the secret that signs your Shopify webhooks | 01, 02, 03, 03b |
Shopify - client credentials (Custom Auth) | Custom Auth | JSON below | 03 |
Shopify - jeton Admin API (X-Shopify-Access-Token) | Header Auth | Name X-Shopify-Access-Token, value = the token | 03b |
SMTP - alertes | SMTP | Your mail server | 04 |
HubSpot scopes for the service key: crm.objects.contacts.write and crm.objects.deals.write. Add crm.schemas.contacts.write and crm.schemas.deals.write for workflow 00 only, and remove them afterwards.
Custom Auth content for workflow 03 (placeholders to replace):
{
"headers": { "Content-Type": "application/x-www-form-urlencoded" },
"body": {
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"grant_type": "client_credentials"
}
}
The header is needed: in n8n 2.46.6, a Custom Auth credential with only a body, or combined with the HTTP Request node’s form body option, sends JSON, while Shopify documents this call as application/x-www-form-urlencoded. The bytes sent were checked on the wire against a local server.
Import
With the five credentials already created. Editor: workflow menu > Import from File (the menu also offers Import from URL; it was not tested with raw GitHub URLs). CLI on a self-hosted instance:
n8n import:workflow --input=workflows/01-client-shopify-vers-contact-hubspot.json
With Docker, copy the files into the container and run the CLI as the node user (the syntax in n8n’s CLI documentation):
docker cp workflows <container>:/tmp/kit-workflows
docker exec -u node <container> n8n import:workflow --input=/tmp/kit-workflows/01-client-shopify-vers-contact-hubspot.json
By default the CLI deactivates every imported workflow. Nothing runs until you publish. Import 03 or 03b, not both: they share the webhook path shopify-segmentation.
Placeholders to replace
| Workflow | Node | Value in the file | Replace with |
|---|---|---|---|
01 | Valid signature and shop? | YOUR_SHOP.myshopify.com | the shop’s *.myshopify.com domain, exactly as Shopify sends it in X-Shopify-Shop-Domain |
02 | Valid signature and shop? | YOUR_SHOP.myshopify.com | the shop’s *.myshopify.com domain, exactly as Shopify sends it in X-Shopify-Shop-Domain |
03 | Valid signature and shop? | YOUR_SHOP.myshopify.com | the shop’s *.myshopify.com domain, exactly as Shopify sends it in X-Shopify-Shop-Domain |
03 | Shopify: get a token (client credentials) | https://YOUR_SHOP.myshopify.com/admin/oauth/access_token | your shop domain (YOUR_SHOP part only) |
03 | Shopify GraphQL: read the customer | https://YOUR_SHOP.myshopify.com/admin/api/2026-10/graphql.json | your shop domain (YOUR_SHOP part only) |
03b | Valid signature and shop? | YOUR_SHOP.myshopify.com | the shop’s *.myshopify.com domain, exactly as Shopify sends it in X-Shopify-Shop-Domain |
03b | Shopify GraphQL: read the customer | https://YOUR_SHOP.myshopify.com/admin/api/2026-10/graphql.json | your shop domain (YOUR_SHOP part only) |
04 | Send the alert email | alertes@YOUR_DOMAIN.tld | sender address accepted by your SMTP server |
04 | Send the alert email | vous@YOUR_DOMAIN.tld | the mailbox that receives the alerts |
Search the JSON before importing if you prefer: grep -n "YOUR_" workflows/*.json.
Values you may change
| Where | Field | Default | Notes |
|---|---|---|---|
| 02 > Deal settings | hubspot_pipeline | default | Internal ID of the pipeline, not its label. |
| 02 > Deal settings | hubspot_dealstage | closedwon | Internal ID of the stage. closedwon is the ID of “Closed Won” in the default pipeline according to a HubSpot community thread; the API reference does not say so. Check yours. |
| 03, 03b > Segmentation settings | seuil_recurrent | 2 | Orders needed for the recurrent segment. |
| 03, 03b > Segmentation settings | seuil_fidele | 4 | Orders needed for the fidele segment. Example values, not advice. |
| 00 > both HTTP nodes | groupName | contactinformation, dealinformation | Change if the properties belong in another group. |
Shopify webhooks
Store admin > Settings > Notifications > Webhooks > Create webhook (labels may vary). Format JSON, API version 2026-10, and the production URL (/webhook/..., not /webhook-test/...).
| Workflow | Shopify event | URL |
|---|---|---|
| 01 | Customer creation and customer update (two webhooks, same URL) | https://YOUR-N8N/webhook/shopify-client |
| 02 | Order payment (orders/paid) | https://YOUR-N8N/webhook/shopify-commande-payee |
| 03 or 03b | Order payment (orders/paid) | https://YOUR-N8N/webhook/shopify-segmentation |
The signing secret goes into the Crypto credential. For a webhook declared by an app it is that app’s client secret. For a webhook created in the admin, the admin shows the store’s signing key on the webhooks page; the exact location was not confirmed from Shopify’s own documentation, so check it on your screen.
A webhook that fails too often can be deleted. Shopify’s help center says a webhook created in the admin is removed when its address keeps answering something other than 200, and that Shopify sends its failure email only for webhooks created by an app. An unreplaced placeholder, a mistyped secret or an unpublished workflow all produce 401 or 404. Replace the placeholders and publish before creating the webhook, use Send test, and look at the webhook list again after 24 hours.
Order of operations
- Create the five credentials with the exact names and types from the table above.
- Import the workflows.
- Replace the placeholders in each node (or in the JSON before importing; the result is the same).
- Run workflow 00 once from the editor. Publishing it is not needed.
- Publish 04 first. n8n 2.x runs the published version; an Error workflow that is not published does not run (observed in 2.46.6).
- In 01, 02 and 03 (or 03b): workflow settings > Error workflow > the 04 workflow. Then publish them. Any later change only takes effect after publishing again.
- Create the Shopify webhooks on the production URLs. Use Send test.
- Replay with the script on the testing page before relying on any of it.
Instance variables worth setting
| Variable | Why |
|---|---|
N8N_WEBHOOK_URL | Behind a reverse proxy, the public base URL n8n shows for webhooks. Without it, the production URL displayed in the editor may not be the one Shopify can reach. |
EXECUTIONS_DATA_PRUNE, EXECUTIONS_DATA_MAX_AGE | Failed executions keep the webhook body, so customer data. n8n documents the defaults as pruning on and 336 hours (14 days). Set the age to what your data protection policy allows. |
n8n’s documentation: endpoint variables and execution variables. The step-by-step explanation, with the reasoning, is in the guide (in French).