Plugin Hooks

A hook is a place where Broadcast calls your code. This page helps you pick one. Each hook then has its own page, with a full example that you can copy.

Choose by what you want

I want to…	Use
React when something happens, such as a signup or a bounce	Events Hook
Do a job every day or every hour	Schedules Hook
Add a step to a sequence	Sequence Steps Hook
Put a value in an email for each person	Merge Tags Hook
Change how a value looks in an email	Liquid Filters Hook
Skip or change a broadcast for some people	Before Send Hook
Let a reader click a link in an email and run my code	Public Actions Hook
Let another system call my plugin	API Endpoints Hook
Send my plugin’s events to another system	Plugin Events and Segment Rules
Give the AI assistant a new skill	AI Tools Hook
Clean up data outside Broadcast when a person is deleted	Subscriber Deleted Hook
Let people build segments from my data	Plugin Events and Segment Rules
Show a screen inside Broadcast	Plugin Pages

All hooks at a glance

Hook	Manifest key	Function	Time limit	When it fails
Events	`hooks.events`	`onEvent`	10 seconds	Tried again, up to 5 times
Schedules	`hooks.schedules`	`onSchedule`	10 seconds	Tried again, up to 3 times, then waits for the next run
Sequence steps	`hooks.sequenceSteps`	`sequenceSteps.<name>`	10 seconds	The step is tried again, up to 5 times
Merge tags	`hooks.mergeTags`	`mergeTags.<name>`	5 seconds	The value is empty. The email goes out
Liquid filters	`hooks.liquidFilters`	`liquidFilters.<name>`	5 seconds	The value is empty. The email goes out
Before send	`hooks.beforeSend`	`beforeSend`	5 seconds	No change. The email goes out
Public actions	`hooks.publicActions`	`publicActions.<name>`	5 seconds	The person sees a general message
API endpoints	`hooks.apiEndpoints`	`apiEndpoints.<name>`	10 seconds	The caller gets HTTP 502
AI tools	`hooks.aiTools`	`aiTools.<name>`	10 seconds	The assistant gets an error
Subscriber deleted	`hooks.onSubscriberDeleted`	`onSubscriberDeleted`	10 seconds	Tried again, up to 5 times
Page data	none (`ui.pages`)	`pageData`	10 seconds	The page gets an error

Three rules for every hook

Be safe to run twice. A failed call is tried again, and an event can arrive more than once. Ask yourself what happens if your function runs twice with the same input. See each hook’s page for how to handle it.

Be quick. Do one job and return. If you have thousands of items, use bulk calls, and do the work over several runs of a schedule.

Throw when the work failed. If your hook throws, Broadcast knows that the work did not finish, and it can try again. If you catch the error and hide it, nobody knows.

But note this limit: a plugin that fails 20 times in a row is turned off in every channel, and the admins get an email. One success resets the count.

The two shapes of a hook

Some hooks are one function:

export default definePlugin({
  async onEvent(event, ctx) {},
});

Others are a group of named functions. The name must match the name in the manifest:

export default definePlugin({
  mergeTags: {
    async tier(input, ctx) {},
  },
});

Hook names use lower case letters, digits and _, start with a letter and have at most 40 characters.