Skip to content

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

  1. 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.

    terminal
    hooksmith init
    hooksmith new shopify-orders --preset shopify --yes
  2. 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.yaml
    apiVersion: 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: secret
    
  3. Step 3: Store your Slack webhook URL

    Paste the Slack URL at the hidden prompt. It is stored encrypted and never appears in the YAML.

    terminal
    hooksmith secrets set DESTINATION_URL
  4. 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 }
      ]
    }
    terminal
    hooksmith test shopify-orders --payload ./order.json
    output
    payload: ./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"
    }
  5. Step 5: Deploy and copy the ingest URL

    The URL is printed on stdout.

    terminal
    hooksmith deploy shopify-orders
    # https://hooksmith.tech/h/<id>
  6. 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.

    terminal
    printf %s "$SHOPIFY_SECRET" | hooksmith secrets set SHOPIFY_WEBHOOK_SECRET
  7. 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.
terminal
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 &#x27; or &amp;.

    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.