How to set up webhooks with Shopify on Tenklo

Shopify webhooks notify your app when something changes in a store — an order is created, a product is updated, a customer is deleted. You register webhooks against Shopify's Admin API with the callback address set to your Tenklo webhook URL; Tenklo verifies the request and routes it to the right connection.

How it worksCopy Anchor Link

1. You register a webhook via Shopify's Admin API (REST or GraphQL), pointing the callback address at your Tenklo webhook URL.
2. Shopify sends a POST request to that URL when the subscribed event occurs, signing it with X-Shopify-Hmac-Sha256 and including the X-Shopify-Topic and X-Shopify-Shop-Domain headers.
3. Tenklo verifies the signature, matches the shop domain in X-Shopify-Shop-Domain to the connection's subdomain, and forwards the event to your app.

SetupCopy Anchor Link

1. Get your Tenklo webhook URLCopy Anchor Link

In the Tenklo dashboard, open your Shopify integration and copy the Webhook URL.

2. Register the webhook in ShopifyCopy Anchor Link

Registering a webhook for a topic requires the scope that grants read access to the underlying resource (for example, read_orders for orders/create). Add the scope to your Shopify integration's Scopes field in the Tenklo dashboard and re-authorize the connection if it was created before the scope was added.

curl -X POST "https://api.tenklo.dev/proxy/admin/api/2025-01/webhooks.json" \
  -H "Authorization: Bearer <NANGO-API-KEY>" \
  -H "Provider-Config-Key: <INTEGRATION-ID>" \
  -H "Connection-Id: <CONNECTION-ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "topic": "orders/create",
      "address": "<NANGO-WEBHOOK-URL>",
      "format": "json"
    }
  }'

Repeat for each topic you want to receive. REST topics use lowercase slash-separated names (orders/create); the GraphQL enum uses the equivalent screaming-snake-case name (ORDERS_CREATE).

Webhook payloadCopy Anchor Link

The POST body is the raw resource as JSON — the same shape as the REST Admin API response for that resource, with a numeric id (not a GraphQL global ID), regardless of whether you registered the webhook via REST or GraphQL. Example for orders/create:

{
  "id": 820982911946154508,
  "order_number": 1001,
  "email": "[email protected]",
  "financial_status": "paid",
  "currency": "USD",
  "total_price": "398.00",
  "line_items": [
    {
      "id": 866550311766439020,
      "title": "IPod Nano - 8GB",
      "quantity": 1,
      "price": "199.00"
    }
  ],
  "customer": {
    "id": 115310627314723954,
    "email": "[email protected]"
  }
}

Every delivery also includes these headers:

Connection matchingCopy Anchor Link

Tenklo matches an incoming webhook to a connection using the shop domain in the X-Shopify-Shop-Domain header against the connection's subdomain. No extra configuration is needed on the connection.

Signature verificationCopy Anchor Link

• Shopify (OAuth): Nango verifies X-Shopify-Hmac-Sha256 automatically using your integration's client secret — no extra setup needed.
• Shopify (API Key): set a Webhook Secret on the integration in the Tenklo dashboard, matching the secret configured when you subscribed the webhook, so Tenklo can verify the signature against it.

Handle the webhookCopy Anchor Link

Once routed to a connection, you have two options:

• Forward it to your app — Tenklo forwards the event to your webhook URL with connection attribution. See External webhook forwarding.
• Process it in a sync — run a sync when the webhook arrives using webhookSubscriptions and onWebhook in a sync script. See Real-time syncs.

Supported eventsCopy Anchor Link

Tenklo can route any topic Shopify delivers, since routing only depends on the X-Shopify-Shop-Domain header. Common topics:

For the full list, see Shopify's webhook topics reference.

Rollback strategyCopy Anchor Link

To stop webhooks, delete the subscription using the id Shopify returned when you created it:

1. REST: send a DELETE request to /admin/api/2025-01/webhooks/<id>.json.
2. GraphQL: call the webhookSubscriptionDelete mutation with that id.

Deleting a subscription stops delivery immediately. Re-create it with the steps above to resume.