Skip to content

Provider guide

Shopify webhooks with Hooksmith

To verify a Shopify webhook, compute a base64 HMAC-SHA256 of the raw request body with your app's client secret and compare it with the X-Shopify-Hmac-Sha256 header. Hooksmith runs that check on every request, then filters the order or product event and forwards a reshaped body to your endpoint.

How Shopify signs webhooks

Hooksmith checks X-Shopify-Hmac-Sha256 against the raw request bytes.

Header
X-Shopify-Hmac-Sha256.
Algorithm
HMAC-SHA256, base64 encoded, compared in constant time.
What is signed
The raw request body.
Key
The app's client secret, or the signing secret Shopify shows for webhooks created in the store admin.
Replay window
None. The signature has no timestamp, so there is no tolerance setting.
  • A failed check answers 401 VERIFICATION_FAILED and stores nothing.
  • A second request with the same X-Shopify-Webhook-Id within 24 hours is reported as a duplicate and is not delivered again.

Set it up

Hooksmith turns the provider preset into a hook you own. The signing secret exists before the endpoint does, so store it first, then deploy, then enter the URL in the provider dashboard. Secrets live in your workspace vault and never go in the YAML. Store SHOPIFY_WEBHOOK_SECRET, DESTINATION_URL.

  1. In the Shopify admin, open Settings, then Notifications, then Webhooks.
  2. Create one webhook per topic the example uses, orders/create and orders/cancelled, each with format JSON and the same /h/<id> URL that hooksmith deploy printed.
  3. Store the matching secret as SHOPIFY_WEBHOOK_SECRET: the app's client secret, or the signing secret Shopify displays for store-created webhooks.
terminal
hooksmith login
hooksmith new shopify-paid-orders --preset shopify --yes
# paste the example hook into .hooksmith/hooks/shopify-paid-orders.yaml
hooksmith secrets set SHOPIFY_WEBHOOK_SECRET
hooksmith secrets set DESTINATION_URL
hooksmith test shopify-paid-orders --payload ./order.json --header "X-Shopify-Topic: orders/create"
hooksmith deploy shopify-paid-orders   # prints the /h/<id> URL

hooksmith new writes the preset's starter hook. Replace its contents with the example below, or edit it by hand. The CLI's built-in test sample is generic, so pass your own payload with --payload; a matching one is in the next section. This example reads request headers, so the test command also passes them with --header (CLI 0.6.4 or later). The command reference is in the docs.

Forward new paid orders and cancellations

Shopify puts the topic in the X-Shopify-Topic header, which a condition reads as @headers.x-shopify-topic. This hook accepts two topics, orders/create and orders/cancelled, skips every other topic, and skips new orders that are not yet paid. The topic is included in the body it sends.

.hooksmith/hooks/shopify-paid-orders.yaml
apiVersion: hooksmith/v1
kind: Hook
metadata:
  name: shopify-paid-orders
  description: New paid orders and cancellations to the fulfilment service
spec:
  source:
    preset: shopify
  destinations:
    - name: fulfilment
      url: ${DESTINATION_URL}
      method: POST
      timeout: 8s
      retries:
        max: 5
        backoff: exponential
        initialDelay: 1s
  transform:
    engine: handlebars
    fields:
      topic: "{{{@headers.x-shopify-topic}}}"
      order: "{{{name}}}"
      total: "{{{total_price}}}"
      currency: "{{{currency}}}"
      email: "{{{default email customer.email}}}"
  conditions:
    - if: '@headers.x-shopify-topic != "orders/create" && @headers.x-shopify-topic != "orders/cancelled"'
      then:
        skip: true
    - if: '@headers.x-shopify-topic == "orders/create" && financial_status != "paid"'
      then:
        skip: true
  variables:
    - name: SHOPIFY_WEBHOOK_SECRET
      from: secret
    - name: DESTINATION_URL
      from: secret
order.json
{
  "name": "#1001",
  "email": "jon@example.com",
  "total_price": "199.00",
  "currency": "USD",
  "financial_status": "paid",
  "cancelled_at": null
}
  • DESTINATION_URL is a workspace secret, so the URL stays out of the YAML. Store it with hooksmith secrets set DESTINATION_URL.
  • Values use triple braces so quotes, ampersands, apostrophes and equals signs reach your endpoint as typed. With double braces, template output is HTML-escaped.
  • Create one Shopify webhook per topic and point both at this hook. The hook tells them apart by the header, not by the body.
  • In a condition you can also write @headers["x-shopify-topic"]. In a template the form is {{@headers.x-shopify-topic}}. Names are lowercase, so @headers.X-Shopify-Topic fails validation.
  • A local hooksmith test sends no request headers unless you pass them, so without --header "X-Shopify-Topic: orders/create" this hook reports the sample as skipped. In the dashboard, the Send test event panel has a Headers box for the same purpose. The --header flag needs CLI 0.6.4 or later.

Shopify topics to subscribe to

Create one Shopify webhook per topic. You can point several topics at the same hook and tell them apart with @headers.x-shopify-topic, or give each topic its own hook.

orders/create
A new order was placed.
orders/paid
An order was fully paid.
orders/cancelled
An order was cancelled.
orders/fulfilled
An order was fulfilled.
refunds/create
A refund was created.
customers/create
A customer was created.
products/update
A product changed.
app/uninstalled
The app was removed from a store.

Test against localhost

The Hooksmith desktop app for Mac can tunnel stored events to a server on your machine. In raw mode it replays the original body bytes and the stored provider headers. Proxy headers such as x-forwarded-host are never stored, so they are not replayed. The target must be localhost, 127.0.0.1, [::1] or a *.localhost name. Get it on the download page.

Shopify signatures carry no timestamp, so an older event can be resent.

Questions

How do I verify a Shopify webhook HMAC?

Compute HMAC-SHA256 of the raw request body with your app's client secret, base64 encode the digest, and compare it in constant time with the X-Shopify-Hmac-Sha256 header. The body must be the raw bytes, not parsed and re-serialized JSON. A hook with source.preset: shopify does this for every request.

Does Shopify retry webhooks?

Yes. Shopify expects a 200 response within five seconds and retries failed deliveries 8 times over the next 4 hours. Hooksmith answers 200 once the event is verified and stored, then delivers to your endpoint on its own retry schedule, so a slow endpoint of yours does not use up Shopify's retries.

How are duplicate Shopify deliveries handled?

Hooksmith uses the X-Shopify-Webhook-Id header as a dedupe key for 24 hours. A repeat with the same id is acknowledged with a duplicate status and is not delivered again. To deliver an event Hooksmith already accepted again, use hooksmith replay <event-id>, which skips the duplicate check. If you subscribe the same topic twice, each subscription has its own id and both are delivered.

Which secret does Shopify sign with?

For an app, it is the app's client secret. Webhooks created in the store admin show their own signing secret. Store whichever applies as SHOPIFY_WEBHOOK_SECRET. After rotating an app secret, Shopify says the new digest can take up to an hour to apply.

Can I filter by Shopify topic?

Yes. The topic is in the X-Shopify-Topic header, which a condition reads as @headers.x-shopify-topic, for example @headers.x-shopify-topic != "orders/create". Header names are lowercase there. You still choose which topics Shopify sends when you create each webhook, and you can add body fields such as financial_status or cancelled_at to the same condition.

Other providers

All providers are listed on webhook providers. Hooks are metered by events processed: see pricing.