Shopify source

The Shopify source enables you to receive Shopify webhook events directly in Knock. Shopify sends webhook callbacks when events occur in your store, such as a new customer signing up, an order being placed, or a fulfillment being shipped. Knock verifies each payload using your Shopify webhook signing secret, identifies the event topic from the X-Shopify-Topic header, and executes the actions you configure.

This integration is useful for building ecommerce notifications: triggering order confirmations when customers check out, syncing Shopify customer data into Knock when profiles are created or updated, and powering downstream notifications like shipping updates or cancellation alerts as you add the topics you need.

Knock supports ingesting any of Shopify's supported webhook topics, so you can map them to actions as your needs evolve.

Shopify supports two distinct ways to create webhooks, and Knock works with both. The payload format, headers, and signature verification are identical — only the setup path differs. Pick the option that matches how you operate your Shopify store.

A store owner adds webhook destinations manually in the Shopify admin panel under Settings > Notifications > Webhooks. The signing secret is displayed in that same section and is shared across every webhook on the store. This path is the best fit for merchants who run their own store and want to forward events to Knock without writing a Shopify app. Learn more.

A Shopify app developer declares webhook subscriptions in the app's shopify.app.toml configuration, or creates them at runtime using the webhookSubscriptionCreate GraphQL mutation on the Admin API. The signing secret is the app's API client secret, so a single secret verifies webhooks from every store that installs the app. This path is the best fit for teams building a Shopify app or managing webhook subscriptions across many stores. Learn more.

Whichever path you choose, the steps for setting up the source in Knock are the same. Once the source exists in Knock, follow the section below that matches your setup.

• A Knock account with at least one environment configured.
• Either access to the Shopify admin panel for the store you want to ingest events from (for the admin path), or a Shopify app with permission to create webhook subscriptions on the stores you want to ingest from (for the app path).

These steps are the same regardless of which Shopify path you use.

Use this path if you're a store owner and want to forward events directly from a single Shopify store without building an app.

Use this path if you're building a Shopify app and want webhook subscriptions to be installed automatically on every store the app runs on. You can declare subscriptions in your app's configuration file with the Shopify CLI, or create them at runtime with the Admin GraphQL API.

Once configured, Shopify sends webhook events to Knock in real time. Knock verifies each payload by computing an HMAC-SHA256 of the raw request body using your signing secret and comparing it to the base64-encoded value in the X-Shopify-Hmac-Sha256 header. You can verify that events are arriving by checking the event logs on the source environment page.

Shopify sends events for customer and order lifecycle changes. Below are the topics Knock pre-configures with default action mappings. You can enable or disable individual topics, or add new ones, from the source environment configuration.

Event topic	Action	Description
customers/create	Identify user	A new customer was created in your store
customers/update	Identify user	A customer's profile details were updated
orders/create	Identify user	Identifies the order's customer in Knock before the workflow is triggered
orders/create	Trigger order-confirmation workflow	Triggers a workflow with the customer as the recipient and the order as data

Customer events use the top-level body.id as the Knock user ID. The two orders/create mappings work together: the identify action upserts the customer from body.customer.* (with body.customer.id as the user ID) so the workflow trigger that runs right after can address that same customer as the recipient. The full Shopify order payload is sent as the workflow's trigger data, so your templates have access to line items, totals, shipping address, and order metadata.

To use the order mapping out of the box, create a workflow in Knock with the key order-confirmation. You can rename the workflow key at any time by editing the action mapping.

Most Shopify customers extend the defaults with a few additional notification flows. Common topics worth adding as custom mappings:

Event topic	Typical action	Description
orders/paid	Trigger a payment-received workflow	An order's payment was captured
orders/fulfilled	Trigger an order-shipped workflow	An order was fulfilled, often with tracking information
orders/cancelled	Trigger an order-cancelled workflow	An order was canceled, often with associated refunds
customers/delete	Delete the user in Knock	A customer was deleted from your store

For order topics, use body.customer.id as the workflow recipient and send body as the workflow data, matching the pattern of the pre-configured orders/create mapping. See the Shopify webhook topics documentation for the full list of available events.

You can modify the default action mappings or add new ones for any topic Knock receives from Shopify. For details on how field mapping works with dot-notation paths, see the custom source page.

Shopify puts the event topic in the X-Shopify-Topic HTTP header instead of the JSON body, so the Shopify source extracts the event type from headers.x-shopify-topic. You can reference other Shopify headers in your mappings using the same dot-notation — for example, headers.x-shopify-shop-domain to differentiate between stores when a single Knock environment ingests events from multiple Shopify stores or from many installs of the same Shopify app.

If a single topic maps to multiple actions, Knock executes those actions in a fixed order. See execution order for multiple mappings.

If you need to map Shopify events to actions beyond triggering workflows, see the full list of available actions in the sources overview.

Knock automatically configures idempotency for the Shopify source so duplicate events are not processed twice. By default, Knock uses headers.x-shopify-webhook-id from the Shopify webhook payload as the idempotency key. Shopify generates a unique ID per webhook delivery and includes it in the X-Shopify-Webhook-Id header, which makes it a reliable way to deduplicate retries.

You can change the idempotency key field or disable idempotency checks from the Settings tab in your source environment configuration. Events without an idempotency key attribute are processed normally.

For details on how Knock handles idempotent events, key validation rules, and the default 24-hour idempotency window, see the source event idempotency section of the sources overview.