Shopify Webhook

Documentation Index

Fetch the complete documentation index at: https://docs.streamkap.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

Prerequisites

• A Shopify store with Admin access (required to install apps and register webhooks).
• A Shopify Partners account so you can create a Dev Dashboard app for OAuth credentials (recommended) — or an existing legacy custom app with a permanent access token.
• A Streamkap workspace with permission to create source connectors.
• A clear list of the Shopify resources you want to capture (orders, products, customers, etc.).

​

How It Works

1. Endpoint provisioning — When you create the source, Streamkap generates a unique HTTPS webhook URL and an API key.
2. Shopify subscriptions — In Shopify, you register webhook subscriptions for the topics you want (orders/create, products/update, …) pointing at the Streamkap URL with the API key passed as a query parameter.
3. Header-based routing — Each incoming request carries an X-Shopify-Topic header (orders/create, customers/delete, etc.). The Shopify payload router maps the resource segment to a topic — orders/* events go to orders, products/* events go to products, and so on.
4. Key extraction — The router pulls the resource id from the JSON body and uses it as the Kafka message key, enabling upsert-style consumption downstream.
5. HMAC verification (optional) — When you provide the Shopify app’s client secret, each payload is verified against the X-Shopify-Hmac-Sha256 header. Invalid payloads are rejected and (if configured) routed to the DLQ.
6. Optional flattening / fan-out — Nested fields can be promoted to top level, and array fields (line items, variants, addresses) can be fanned out into their own topics.
7. Optional snapshot — For initial loads or ad-hoc backfills, the source queries the Shopify GraphQL Admin API with cursor pagination and emits records alongside the live webhook stream.

​

Streamkap Setup

​

1. Create the Source

1. Navigate to Sources and choose Shopify.
2. Give the source a memorable Name (for example, shopify-prod).

​

2. Connection Settings (Auth tab)

​

3. Schema (Shopify Resources)

​

4. Settings

​

5. Save and Copy the Endpoint

​

Shopify Setup

https://<webhook-url>?api_key=<API_KEY>

​

1. Create an App in the Partners Dashboard

Note: As of January 2026, Shopify has deprecated legacy custom apps. New apps must be created via the Partners Dashboard. Existing legacy custom apps with permanent tokens still work but cannot be created on new stores.

1. Go to the Shopify Partners Dashboard (create a partner account if needed).
2. Click Apps → Create app → Create app manually.
3. Name it (for example, Streamkap), set the App URL to your Streamkap webhook URL.
4. Click Create app.

​

2. Configure API Scopes

​

3. Install the App and Get Credentials

1. In the app, open Settings and note the Client ID and Client Secret.
2. Install the app on your store (from the Partners Dashboard or via Settings → Apps and sales channels → Develop apps in your store admin) and approve the scopes.

​

Option A — Client credentials grant (recommended)

curl -X POST "https://YOUR-STORE.myshopify.com/admin/oauth/access_token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_type": "client_credentials"
  }'

​

Option B — Static access token (legacy custom apps only)

​

4. Register Webhooks via the GraphQL Admin API

​

Register a single webhook

curl -X POST "https://YOUR-STORE.myshopify.com/admin/api/2024-10/graphql.json" \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: YOUR_ACCESS_TOKEN" \
  -d '{
    "query": "mutation { webhookSubscriptionCreate(topic: ORDERS_CREATE, webhookSubscription: { callbackUrl: \"https://YOUR-WEBHOOK-URL?api_key=YOUR_API_KEY\", format: JSON }) { webhookSubscription { id } userErrors { field message } } }"
  }'

​

Register all common webhooks at once

#!/bin/bash
STORE="YOUR-STORE.myshopify.com"
TOKEN="YOUR_ACCESS_TOKEN"
CALLBACK="https://YOUR-WEBHOOK-URL?api_key=YOUR_API_KEY"
API_VERSION="2024-10"

TOPICS=(
  # Orders
  ORDERS_CREATE ORDERS_UPDATED ORDERS_DELETE
  ORDERS_CANCELLED ORDERS_FULFILLED ORDERS_PAID
  # Products
  PRODUCTS_CREATE PRODUCTS_UPDATE PRODUCTS_DELETE
  # Customers
  CUSTOMERS_CREATE CUSTOMERS_UPDATE CUSTOMERS_DELETE
  # Draft Orders
  DRAFT_ORDERS_CREATE DRAFT_ORDERS_UPDATE DRAFT_ORDERS_DELETE
  # Fulfillments
  FULFILLMENTS_CREATE FULFILLMENTS_UPDATE
  # Inventory
  INVENTORY_ITEMS_CREATE INVENTORY_ITEMS_UPDATE INVENTORY_ITEMS_DELETE
  # Collections
  COLLECTIONS_CREATE COLLECTIONS_UPDATE COLLECTIONS_DELETE
)

for TOPIC in "${TOPICS[@]}"; do
  echo "Creating webhook for $TOPIC..."
  curl -s -X POST "https://$STORE/admin/api/$API_VERSION/graphql.json" \
    -H "Content-Type: application/json" \
    -H "X-Shopify-Access-Token: $TOKEN" \
    -d "{\"query\": \"mutation { webhookSubscriptionCreate(topic: $TOPIC, webhookSubscription: { callbackUrl: \\\"$CALLBACK\\\", format: JSON }) { webhookSubscription { id } userErrors { field message } } }\"}"
  echo
done

​

Verify registered webhooks

curl -s -X POST "https://YOUR-STORE.myshopify.com/admin/api/2024-10/graphql.json" \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: YOUR_ACCESS_TOKEN" \
  -d '{
    "query": "{ webhookSubscriptions(first: 50) { edges { node { id topic endpoint { ... on WebhookHttpEndpoint { callbackUrl } } } } } }"
  }'

​

Delete a webhook

curl -s -X POST "https://YOUR-STORE.myshopify.com/admin/api/2024-10/graphql.json" \
  -H "Content-Type: application/json" \
  -H "X-Shopify-Access-Token: YOUR_ACCESS_TOKEN" \
  -d '{
    "query": "mutation { webhookSubscriptionDelete(id: \"gid://shopify/WebhookSubscription/1234567890\") { deletedWebhookSubscriptionId userErrors { field message } } }"
  }'

​

Via Shopify Admin UI (Quick Setup)

1. In Shopify Admin, go to Settings → Notifications → Webhooks.
2. Click Create webhook.
3. Select the event (for example Order creation).
4. Set format to JSON.
5. Enter your Streamkap webhook URL with the API key appended: https://YOUR-WEBHOOK-URL?api_key=YOUR_API_KEY.
6. Save and repeat for each event.

​

Event Routing Reference

​

Fan-out

orders.line_items, orders.shipping_lines, orders.discount_codes, orders.tax_lines,
orders.fulfillments, products.variants, products.images, products.options,
customers.addresses, draft_orders.line_items, fulfillments.line_items

• _ctx_event_id — the originating X-Shopify-Event-Id for correlation.
• _ctx_shop_domain — the originating X-Shopify-Shop-Domain.

​

HMAC Verification

​

Snapshot

​

Snapshottable Resources

​

Troubleshooting

​

Limitations

• The Shopify Webhook source is currently Beta.
• Shopify expects a 200 response within 5 seconds. The connector responds immediately and processes asynchronously; failures are captured in the DLQ when enabled.
• Snapshot supports only the resources backed by the GraphQL Admin API listed above. Other resources (e.g., fulfillments, shop) are streamed via webhooks only.
• Mandatory Shopify compliance webhooks (customers/data_request, customers/redact, shop/redact) are accepted by the endpoint but currently routed to the unknown topic; you should respond to them out of band per Shopify’s requirements.
• Maximum payload size is 50 MB and maximum header size is 64 KB.
• The connector runs as a single task; horizontal scaling requires multiple source instances.

​

See Also

• Webhook Source — generic webhook source for any HTTP-capable producer.
• Zendesk Webhook — Zendesk-specific webhook source.
• Salesforce CDC — Salesforce CDC + Apex-trigger webhook source.