Skip to main content

Webhooks

Handle webhooks in custom components​

If the API you're building a custom component for supports event-driven notifications (webhooks), it's helpful to include actions that subscribe an instance's flow to a webhook. Generally, we've found that four actions webhook-related actions are helpful to have:

  1. List Webhooks. This action lists all webhooks that are configured in the third-party app. We recommend only displaying webhooks that are pointed at the current instance's flows (otherwise, you'll see webhooks that are configured for other applications). Check out the example in our GitHub examples repo which demonstrates how to reference context.webhookUrls to filter webhooks down to only ones that match your current instance.
  2. Create Webhook This action takes an event (or list of events, like contact.create) and a URL, which can be a webhook URL of a sibling flow. If an ID of a webhook is returned, this action can return that ID. See our examples repo for an example of creating a webhook.
  3. Delete Webhook by ID This action can take an ID of a webhook (fetched by the List Webhooks action), and delete that webhook by ID.
  4. Delete Instance Webhooks This is a handy action to include, as it fetches a list of all webhooks in the third-party, filters them down to only webhooks pointed at the current instance, and removes just those webhooks. You can leverage context.webhookUrls to determine which webhooks to delete. Having this logic baked in to a single action can reduce complexity on your component's users. Check out our examples repo for an example of a Delete Instance Webhooks action.

The above actions assume that an integration builder will create two flows: one that creates webhooks on instance deploy and one that removes webhooks on instance delete. If you'd like to simply that process for users of your component, you can bake webhook logic into a custom trigger's onInstanceDeploy and onInstanceDelete functions. See our examples repo for an example of how to create and delete webhooks automatically when an instance is created or deleted.