Webhook trigger

A webhook trigger lets the other system tell Automation when something happens. It registers the flow’s address with the other system when the flow is switched on, and removes it when the flow is switched off.

The address

Every flow has one webhook address. Collabase hands it to the trigger as context.webhookUrl:

https://your-instance/api/v1/automation/webhooks/<flow id>

Anyone who knows the address can call it. See Webhooks.

Enable, run, disable

export const orderChanged = createTrigger({
  name: "order_changed",
  displayName: "Order changed",
  description: "Starts when an order changes.",
  type: TriggerStrategy.WEBHOOK,
  props: {},
  sampleData: { id: "A1", status: "shipped" },
  onEnable: async (context) => {
    const hook = await registerHook(context.auth, context.webhookUrl);
    await context.store.put("hookId", hook.id);
  },
  onDisable: async (context) => {
    const hookId = await context.store.get<string>("hookId");
    if (hookId) await removeHook(context.auth, hookId);
  },
  run: async (context) => [context.payload.body],
});

Hook	Purpose
`onEnable`	Register `context.webhookUrl` with the other system and store the id of the registration.
`run`	Receives each call and returns the items. Return `[context.payload.body]` to pass the body on as one item, or build several items. Return an empty list to start nothing, for example for a ping.
`onDisable`	Delete the registration, using the stored id.

What `run` receives

context.payload holds the call that arrived:

Field	Content
`body`	The body, read as JSON when it is JSON and as text otherwise.
`queryParams`	The query parameters.
`method`	`POST` or `GET`.

The headers of the call are not handed to the plug. A signature that the other system sends in a header cannot be checked in run. Prefer a system that signs the body or lets you choose a secret that travels in the body or in the address.

Not supported

Handshake and renewal hooks are not called, so a system that first asks the address to answer a challenge cannot be connected with a plug trigger. Use a flow with the built-in Webhook received trigger and answer with Respond to webhook in that case.

Test

A webhook trigger cannot be tested before the flow is published, because the other system sends the data. Switch the flow on, cause an event in the other system and open the run.

Overview

Build flows

Run and publish

Agents and AI

Share and reuse

Workspaces and plugs

Reference

Build a plug

Plug triggers

Plug runtime

Ship a plug

The address

Enable, run, disable

What `run` receives

Not supported

Test

​The address

​Enable, run, disable

​What run receives

​Not supported

​Test

​Related

The address

Enable, run, disable

What `run` receives

Not supported

Test

Related