Articles in this section

Configure webhooks in multi-instance flows

When a multi-instance flow starts with a webhook listener, every instance shares that listener by default. This works when all instances can receive data at the same URL with the same authentication. When each instance needs its own URL or shared secret, for example one listener per store, you replace the listener in each instance with a JSON override. This article explains both approaches and how to choose between them.

Choose a listener approach

The right approach depends on whether the sending systems can share one webhook URL and secret.

Approach How it works Use it when
Shared listener Every instance receives data at the base flow's listener URL and uses its shared secret. All senders can post to one URL with one secret.
Per-instance listener Each instance replaces the base flow's listener with its own listener export. Each sender needs its own URL or secret, and you have a manageable number of instances.

If every instance needs its own listener and you have many instances, separate standard flows can be easier to maintain than one JSON override per instance.

Use the shared listener

With a shared listener, you configure the webhook once on the base flow, and every instance inherits it.

  1. Configure the webhook listener on the base flow. For an example, see Set up a Shopify webhook listener.
  2. Register the listener's URL and secret in each sending system.
  3. In each instance that needs it, add a transformation or filter for the incoming payload through a JSON override on the listener export. The listener step doesn't appear in the Customizable properties panel, so you can't set these in the Simple view. For the override structure, see Override instance configurations with JSON.

Instances can't override an individual listener property, such as the URL or shared secret. To give an instance its own URL or secret, replace the listener as described in Replace the listener for an instance in this article.

Replace the listener for an instance

To give an instance its own webhook URL or shared secret, create a separate listener export and use a JSON override to replace the base flow's listener in that instance.

  1. Create a webhook listener export with the URL and secret the instance needs: go to Resources, select Exports, select Create export, and then select Webhook as the application. Record the new export's resource ID.
  2. Get the resource ID of the base flow's listener. See Override instance configurations with JSON.
  3. Open the instance's JSON view, and add an override that replaces the listener:

    {
      "exports": [
        {
          "_abstractId": "6901a2b3c4d5e6f7a8b9c914",
          "_id": "6901a2b3c4d5e6f7a8b9c7ff"
        }
      ]
    }
    

    Set _abstractId to the base flow listener's ID and _id to the replacement listener's ID.

  4. Select Save.
  5. Register the replacement listener's URL and secret in the sending system for this instance.

Don't add __listenerIdsToIndex to the override. integrator.io manages that property and populates it on instances automatically.