Guide
How to forward Shopify webhooks to Slack with a transformed message
Shopify posts a large JSON order to your endpoint, and Slack incoming webhooks expect {"text": "..."}. Put a Hooksmith hook between them: the Shopify preset verifies the X-Shopify-Hmac-Sha256 signature, a Handlebars transform builds the text, and Hooksmith posts it to your Slack webhook URL. You write the hook as YAML, test it against a sample order with hooksmith test, then deploy and paste the ingest URL into Shopify.
Before you start
- The Hooksmith CLI, installed and logged in (curl -fsSL https://hooksmith.tech/install.sh | bash, then hooksmith login).
- A Slack incoming webhook URL for the channel you want. Create one in Slack; it starts with https://hooks.slack.com/services/.
- Access to your store's webhook settings in the Shopify admin.
Steps
Step 1: Create the hook from the Shopify preset
--preset shopify writes a starter hook with the signature check already set. Run init first if this directory has no .hooksmith/ folder.
terminalhooksmith init hooksmith new shopify-orders --preset shopify --yes
Step 2: Replace the YAML with the Slack transform
Open .hooksmith/hooks/shopify-orders.yaml and replace its contents with the hook below. It changes two things in the starter: fields.text is the body Slack reads, and the cancelled_at condition swaps in a shorter message for cancelled orders.
Handlebars escapes {{ }} output as HTML, which would turn the apostrophe in a product title into '. Triple braces, {{{title}}}, print the text as it is. Use them for free text that goes to chat.
The destination URL stays ${DESTINATION_URL} on purpose. hooksmith test supplies a placeholder for that one secret, so the offline test in the next steps works.
.hooksmith/hooks/shopify-orders.yamlapiVersion: hooksmith/v1 kind: Hook metadata: name: shopify-orders description: Shopify orders to Slack spec: source: preset: shopify destinations: - name: primary url: ${DESTINATION_URL} method: POST timeout: 8s retries: max: 3 backoff: exponential initialDelay: 500ms transform: engine: handlebars fields: text: |- *New order {{name}}* {{total_price}} {{currency}} from {{email}} {{#each line_items}} - {{quantity}} x {{{title}}} {{/each}} conditions: - if: cancelled_at then: transform: fields: text: "*Order {{name}} was cancelled* ({{total_price}} {{currency}})" variables: - name: SHOPIFY_WEBHOOK_SECRET from: secret - name: DESTINATION_URL from: secretStep 3: Store your Slack webhook URL
Paste the Slack URL at the hidden prompt. It is stored encrypted and never appears in the YAML.
terminalhooksmith secrets set DESTINATION_URL
Step 4: Test it offline with a sample order
Save a sample order as order.json. Hooksmith evaluates the conditions and the transform locally and prints the body it would send. No destination is called.
order.json{ "id": 820982911946154500, "name": "#1001", "email": "ada@example.com", "total_price": "59.80", "currency": "USD", "cancelled_at": null, "line_items": [ { "title": "Men's Shirt & Tie", "quantity": 2 }, { "title": "Socks", "quantity": 1 } ] }terminalhooksmith test shopify-orders --payload ./order.json
outputpayload: ./order.json skipped: false destinations: primary body: { "text": "*New order #1001*\n59.80 USD from ada@example.com\n- 2 x Men's Shirt & Tie\n- 1 x Socks\n" }Step 5: Deploy and copy the ingest URL
The URL is printed on stdout.
terminalhooksmith deploy shopify-orders # https://hooksmith.tech/h/<id>
Step 6: Point Shopify at the URL and store the signing secret
In the Shopify admin, open Settings, then Notifications, then Webhooks. Add a webhook for the order creation event, set the format to JSON, and paste the ingest URL.
Store the secret Shopify signs with as SHOPIFY_WEBHOOK_SECRET: the app's client secret, or the signing secret Shopify shows for webhooks created in the admin.
terminalprintf %s "$SHOPIFY_SECRET" | hooksmith secrets set SHOPIFY_WEBHOOK_SECRET
Step 7: Optional: send the same event to Discord
Discord webhooks read content instead of text, and use **double asterisks** for bold. Store the Discord webhook URL as DESTINATION_URL and use this version of the hook.
.hooksmith/hooks/shopify-orders.yaml (Discord)apiVersion: hooksmith/v1 kind: Hook metadata: name: shopify-orders description: Shopify orders to Discord spec: source: preset: shopify destinations: - name: primary url: ${DESTINATION_URL} method: POST timeout: 8s retries: max: 3 backoff: exponential initialDelay: 500ms transform: engine: handlebars fields: content: |- **New order {{name}}** {{total_price}} {{currency}} from {{email}} {{#each line_items}} - {{quantity}} x {{{title}}} {{/each}} conditions: - if: cancelled_at then: transform: fields: content: "**Order {{name}} was cancelled** ({{total_price}} {{currency}})" variables: - name: SHOPIFY_WEBHOOK_SECRET from: secret - name: DESTINATION_URL from: secret
How to check it works
Check the message before a real order arrives.
- hooksmith test prints the body shown above, with the apostrophe and ampersand intact.
- On the hook's page in the dashboard, choose Send test event and paste the contents of order.json. Test events skip the signature check and do not count toward your monthly usage, but the message is really posted to Slack.
- After a real order, hooksmith logs shopify-orders shows the event with the status delivered.
hooksmith logs shopify-orders
Troubleshooting
Shopify: signature mismatch
The secret stored as SHOPIFY_WEBHOOK_SECRET is not the one Shopify signs with. Set it again with hooksmith secrets set SHOPIFY_WEBHOOK_SECRET, then trigger a new order.
Secret not found: SHOPIFY_WEBHOOK_SECRET (HTTP 400)
The hook is deployed but the secret was never stored. Run hooksmith secrets set SHOPIFY_WEBHOOK_SECRET.
HTTP 404 on the delivery to Slack, with no retries.
A 4xx other than 408, 425 and 429 fails at once. The Slack URL is wrong or was revoked. Set DESTINATION_URL again, then choose Retry delivery on the event in the dashboard. Destination URLs are read again at every attempt.
destination URL must use https
DESTINATION_URL is not an https:// URL. Destinations must be public HTTPS addresses.
The message shows ' or &.
A field uses {{ }} where it needs {{{ }}}. Triple braces skip Handlebars' HTML escaping.
hooksmith test fails with Secret not found: SLACK_WEBHOOK_URL.
hooksmith test only knows BRRR_WEBHOOK, BUILDKITE_TOKEN and DESTINATION_URL, and takes them from your environment or a placeholder. Name the destination secret DESTINATION_URL.