# Receive Shopify webhooks

Point a Shopify store's webhooks at Webhooker, verify the X-Shopify-Hmac-Sha256 signature, and forward orders and products to your app.

Source: https://docs.webhooker.eu/tutorials/shopify/

## Before you start

- Access to the store's **Settings → Notifications**, or a custom app if you
  prefer to register webhooks through the Admin API.

## 1. Create the source

**Sources → Create source**, name it after the store — `shopify-eu` — and copy
the ingest URL.

## 2. Add the webhook in Shopify

Store admin → **Settings → Notifications → Webhooks → Create webhook**:

- **Event** — for example `Order creation`. One webhook per event.
- **Format** — JSON.
- **URL** — the ingest URL.
- **Webhook API version** — the current stable version.

After saving, Shopify shows the store's **webhook signing secret** once, below
the list. Copy it.

## 3. Turn on verification

In Webhooker: **Settings → Authenticate inbound requests** → method **Shopify** →
paste the secret → save.

Shopify signs the raw body with HMAC-SHA256 and sends it base64-encoded in
`X-Shopify-Hmac-Sha256`. Webhooker checks it before storing anything.

One secret covers every webhook in that store, so a second source for the same
store uses the same value. Apps in the Shopify App Store must also answer the
three mandatory GDPR topics —
[Shopify webhook verification and the GDPR webhooks](https://webhooker.eu/blog/shopify-webhook-verification-gdpr)
covers both halves.

## 4. Send a test notification

Use **Send test notification** on the webhook. It appears in the live tail as
`verified`.

Test notifications carry sample data, not a real order, so filters that match
specific values may not fire on them.

## 5. Forward it to your app

**Destinations → Add destination → Create new**, your handler's URL, **Sign
outbound requests** on, save.

## 6. Split by topic

Shopify puts the topic in a header. If one source receives several topics, give
each gateway its own filter:

```json
{
  "operator": "and",
  "rules": [
    { "path": "headers.x-shopify-topic", "op": "eq", "value": "orders/create" }
  ]
}
```

To pass the topic through to your endpoint, add a **set header** rule on that
gateway with a fixed value — the sender's own headers are not forwarded.

## Verify it works

1. Shopify's webhook list shows recent successful deliveries.
2. The Webhooker event is `verified`.
3. The delivery is `succeeded`.

## Troubleshooting

| Symptom | Cause |
| --- | --- |
| Every event is `failed` | The wrong secret — an app's API secret is not the webhook signing secret. |
| Shopify removed the webhook | Shopify disables endpoints that fail repeatedly. Webhooker answers `200` as long as verification passes, so check the event log for `failed` events. |
| Large orders rejected | Payloads over 1 MiB return `413`. |
| Duplicates | Shopify retries, and delivery is at-least-once. Key on `X-Webhooker-Event-Id`. |