Triggered Agents: Fire Tasks on Webhooks and Events

Triggered tasks are the event-driven counterpart to scheduled agents — instead of firing on a cron clock, they fire when you call fire(name, payload), typically from inside a webhook handler or queue consumer. Both run under the same tracing as request-driven agents.

Defining a trigger

Create a trigger.ts file anywhere under a background-tasks directory (conventionally server/triggers/):

server/triggers/order-created/trigger.ts

import { defineTrigger } from 'anvil-sdk/schedule';

export default defineTrigger({
  name: 'order.created',
  run: async (ctx) => {
    const order = ctx.payload as { id: string; total: number };
    await notifyFulfillment(order);
  },
});

string

required

Unique trigger name — this is the identifier you pass to fire().

(ctx: TaskContext) => unknown | Promise<unknown>

required

The task body. Receives a TaskContext with now (when fire was called), payload (whatever you passed to fire), and trace.

Registering and firing triggers

import { TriggerRegistry, loadBackgroundTasks } from 'anvil-sdk/schedule';
import { Tracer, SqliteTraceStore } from 'anvil-sdk/trace';

const tracer = new Tracer(await SqliteTraceStore.open('.anvil/traces.db'));
const { triggers } = await loadBackgroundTasks('server/triggers');

const registry = new TriggerRegistry({ tracer });
triggers.forEach((task) => registry.register(task));

Fire a trigger from any webhook handler or queue consumer:

// server/routes/webhooks/orders/post.ts
import type { Context } from 'anvil-sdk';
import { registry } from '../../../triggers';

export default async function handler(ctx: Context) {
  const payload = await ctx.body();
  await registry.fire('order.created', payload);
  return { received: true };
}

`TriggerRegistry` API

(task: TriggerTask) => this

(name: string) => boolean

Check whether a trigger with this name is registered.

(name: string, payload?: unknown, now?: Date) => Promise<unknown>

Run the named trigger’s run function, passing payload through ctx.payload. Returns whatever run returns. Throws if no trigger is registered under name.

Each fire() call opens a trace span named trigger <name>. If run throws, the span closes with status error and the error propagates back to the caller — unlike scheduled tasks, a triggered task’s failure is not swallowed, since the caller (your webhook handler) usually needs to know it failed to return the right HTTP status.

fire() runs the trigger synchronously, in the same request that called it. For triggers backed by slow or unreliable side effects, queue the actual work inside run (or hand off to a job queue) rather than blocking the webhook response on it.

Defining a trigger

Create a trigger.ts file anywhere under a background-tasks directory (conventionally server/triggers/):

server/triggers/order-created/trigger.ts

import { defineTrigger } from 'anvil-sdk/schedule';

export default defineTrigger({
  name: 'order.created',
  run: async (ctx) => {
    const order = ctx.payload as { id: string; total: number };
    await notifyFulfillment(order);
  },
});

string

required

Unique trigger name — this is the identifier you pass to fire().

(ctx: TaskContext) => unknown | Promise<unknown>

required

The task body. Receives a TaskContext with now (when fire was called), payload (whatever you passed to fire), and trace.

Registering and firing triggers

import { TriggerRegistry, loadBackgroundTasks } from 'anvil-sdk/schedule';
import { Tracer, SqliteTraceStore } from 'anvil-sdk/trace';

const tracer = new Tracer(await SqliteTraceStore.open('.anvil/traces.db'));
const { triggers } = await loadBackgroundTasks('server/triggers');

const registry = new TriggerRegistry({ tracer });
triggers.forEach((task) => registry.register(task));

Fire a trigger from any webhook handler or queue consumer:

// server/routes/webhooks/orders/post.ts
import type { Context } from 'anvil-sdk';
import { registry } from '../../../triggers';

export default async function handler(ctx: Context) {
  const payload = await ctx.body();
  await registry.fire('order.created', payload);
  return { received: true };
}

`TriggerRegistry` API

(task: TriggerTask) => this

(name: string) => boolean

Check whether a trigger with this name is registered.

(name: string, payload?: unknown, now?: Date) => Promise<unknown>

Run the named trigger’s run function, passing payload through ctx.payload. Returns whatever run returns. Throws if no trigger is registered under name.

Get Started

Routing

MCP & Tools

Agent Routes

Observability

Safety & Durability

Memory & RAG

Background Tasks

Triggered Agents: Fire Tasks on Webhooks and Events

Defining a trigger

Registering and firing triggers

`TriggerRegistry` API

See also

Defining a trigger

Registering and firing triggers

`TriggerRegistry` API

See also

​Defining a trigger

​Registering and firing triggers

​TriggerRegistry API

​See also

​Defining a trigger

​Registering and firing triggers

​TriggerRegistry API

​See also

Defining a trigger

Registering and firing triggers

`TriggerRegistry` API

See also

Defining a trigger

Registering and firing triggers

`TriggerRegistry` API

See also