@trigger.dev/sdk 0.0.0-python-preview-20250226140121 → 0.0.0-rc-4-8-0-20261021151928

package/docs/webhooks/channels.mdx

@@ -0,0 +1,154 @@
+---
+title: "Channels (chat frontends)"
+description: "Point Slack (or any chat surface) at an agent: messages become turns and replies post back."
+sidebarTitle: "Channels"
+---
+
+A [session route](/webhooks/session-routing) delivers a verified event to an agent as an [action](/ai-chat/actions): the agent reacts, and the response is a side effect. A **channel** is the other half: the webhook IS the chat surface. Inbound messages become **turns** (the normal `run()` loop), and the agent's reply is posted **back** to the surface. A Slack thread becomes a real conversation with the agent, exactly like the browser chat, just a different frontend.
+
+List channels on a [`chat.agent`](/ai-chat/overview) alongside (or instead of) `events`:
+
+```ts
+import { webhooks } from "@trigger.dev/sdk";
+import { chat } from "@trigger.dev/sdk/ai";
+import { appMentions, slack, webhookSource } from "@trigger.dev/slack";
+import { anthropic } from "@ai-sdk/anthropic";
+
+const slackEvents = webhooks.endpoint.define({ id: "slack", source: webhookSource() });
+
+export const supportAgent = chat.agent({
+  id: "support-agent",
+  channels: [
+    slack({
+      id: "support-slack",
+      endpoint: slackEvents,
+      token: process.env.SLACK_BOT_TOKEN!,
+      startOn: appMentions(),
+    }),
+  ],
+  run: async ({ messages, streamText }) =>
+    streamText({ model: anthropic("claude-sonnet-4-5"), messages }),
+});
+```
+
+The `run()` loop is unchanged: the agent does not know or care that it is talking to Slack. One verified Slack message in a thread is routed to a durable [session](/ai-chat/sessions) keyed to that thread, run as a turn, and the reply is posted into the thread.
+
+## Slack
+
+`slack()` from `@trigger.dev/slack` makes the agent a native Slack agent: the session shows its status, the reply streams into the thread with tool calls as task cards, approvals are buttons and Slack's stop button stops the turn. Shared images and PDFs reach the model, messages sent mid-reply can be folded into it, and the agent can post its own buttons. See [Slack agents](/webhooks/slack) for setup and options.
+
+## Linear
+
+`linear()` from `@trigger.dev/linear` makes the agent a Linear agent: assign it an issue or @mention it and it works the issue inside Linear's agent session UI, with thoughts, actions, a plan and approvals. See [Linear agents](/webhooks/linear).
+
+## Approvals and interactive controls
+
+An agent on a channel can pause a turn to get a human decision, approving a refund or confirming a deletion, and resume once someone clicks a button in the thread. `slack()` renders Approve and Deny buttons for you and collapses them to the decision once clicked; you can replace them, or give a tool its own UI whose click becomes the tool's result (see [Slack agents](/webhooks/slack#approvals-and-buttons)). See [human-in-the-loop](/webhooks/human-in-the-loop).
+
+## Any surface: `chat.channels.custom`
+
+For a surface without a preset, `chat.channels.custom` is the generic connector. You supply the [endpoint](/webhooks/overview) it subscribes to, the session `key`, the `inbound` map, and the egress `send`:
+
+```ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { webhooks } from "@trigger.dev/sdk";
+
+const surface = webhooks.endpoint.define({
+  id: "my-surface",
+  source: webhooks.custom<MyEvent>({ /* verifier config */ }),
+});
+
+const mySurface = chat.channels.custom({
+  id: "my-surface",
+  endpoint: surface,
+  key: "{event.conversationId}",
+  inbound: (e) => e.text,
+  outbound: (reply) => (reply.text ? { text: reply.text } : null), // null posts nothing
+  send: async (message, ctx) => {
+    const ref = await postToMySurface(ctx.event, message.text, ctx.previousRef);
+    return { ref }; // later sends in the same turn get it back as ctx.previousRef
+  },
+});
+```
+
+`send` is called to post the reply. Within a turn, `ctx.previousRef` is the ref you returned from the turn's earlier `send` (the acknowledgement, or the message being streamed), so later sends edit that message instead of posting a new one. Each turn starts without a ref: the next turn's answer is a new message. Return `null` from `outbound` to stay silent (a tool-only turn, say).
+
+An event that `inbound` maps to an empty message (no text, and no file or data parts) runs no turn. A click or system event your surface sends to the same endpoint is dropped rather than answered with an empty prompt.
+
+List the connector in `chat.agent({ channels: [mySurface] })`, which subscribes the agent to the endpoint with the id `agentId:connectorId`. Other subscribers on the endpoint keep receiving its deliveries.
+
+## When a turn fails
+
+When a turn fails (the model or provider returns an error, or the turn throws), the channel shows a short line instead of the error: "Something went wrong answering this. Try again." by default, or the connector's `errorMessage`. If the reply had partly streamed, the line goes after that text. The error is logged on the run, and `outbound` receives it as `reply.error`, so you can render a failure differently.
+
+`errorMessage` is a fixed string, or a function that builds the line from the failure. It receives the `error`, the `partialText` streamed before it failed, the triggering `event` (undefined on a turn the channel didn't start), the `runId`, the `chatId`, and the `defaultMessage`. Return nothing, or throw, to fall back to the default line.
+
+```ts
+slack({
+  id: "slack",
+  endpoint: slackEvents,
+  token: process.env.SLACK_BOT_TOKEN!,
+  startOn: appMentions(),
+  errorMessage: ({ error, runId }) =>
+    error.message.includes("rate limit")
+      ? "I'm getting a lot of requests right now. Try again in a minute."
+      : `Something went wrong answering this. Try again, or share ref ${runId} with support.`,
+});
+```
+
+## Stopping a turn from the channel
+
+A connector can map an event to a control with `onControl`. Returning `{ kind: "stop" }` while a turn is running aborts it through the run's `stopSignal`, exactly like the browser's stop button: the partial reply posts with `stopped: true` and the event is consumed instead of running as a turn. `linear()` and `slack()` map their stop buttons this way; a custom connector might map a `/stop` command:
+
+```ts
+chat.channels.custom({
+  // ...
+  onControl: (e) => (e.text.trim() === "/stop" ? { kind: "stop" } : null),
+});
+```
+
+When nothing is running, the event is handled by `inbound` as an ordinary message. Return `whenIdle: "drop"` to consume it instead: no turn runs, and if the session is waiting on an [approval](/webhooks/human-in-the-loop) the pending tool calls are resolved as stopped and the connector's `cancelInteraction(cancelled, ctx)` takes the controls down (each cancelled call carries the `ref` its controls were posted with). Set `at` to when the user asked (epoch milliseconds), and a stop older than the latest turn is consumed without stopping it or cancelling that turn's approval, so a late or repeated delivery never stops the wrong turn. A stop pressed while the latest turn ran but delivered after it ended is consumed too, rather than handled as a message.
+
+## Status and native streaming
+
+Two more hooks let a connector mirror the session into a surface that has its own notion of an agent, the way `slack()` does:
+
+- `lifecycle(state, ctx)` reports `working` when a turn starts (and every 50 minutes while it runs), `waiting` when it pauses on a human decision, `idle` when it ends for any reason, and `closed` on `chat.close()`. `ctx.firstTurn` and `ctx.prompt` are there to title a new conversation. Calls are serialized, so an older report never lands after a newer one.
+- `stream(ctx)`, with `delivery: "stream"`, returns a per-turn transport `{ text(delta), progress?(event), end(outcome) }`. The runtime feeds it the reply's markdown deltas and tool progress, then calls `end({ stopped, pending, errorText? })` once, with the connector's error line as `errorText` when the turn failed. Resolve `{ delivered: true }` when the reply reached the surface, and the runtime does not post it again. Call `ctx.opened(ref)` once the surface has created the stream message: the ref is saved with the session while the turn runs, and if the worker dies mid-stream the next one calls the connector's `endInterruptedStream(ref, ctx)` before it answers, so the old stream does not look like it is still being written.
+
+## Bound sessions
+
+The first channel message binds the session to its connector and thread. From then on, any turn on that session posts its answer back through the same connector, including turns no channel delivery started: a [`chat.event`](/webhooks/session-routing#answering-into-a-channel) action that returns `chat.turn()`, or a message from a browser client sharing the session via [`chat.createWatchToken`](/ai-chat/reference). `slack()` binds to the team, channel, thread and the user it is answering; a custom connector opts in with `bind`:
+
+```ts
+chat.channels.custom({
+  id: "my-surface",
+  endpoint: surface,
+  key: "{event.conversationId}",
+  inbound: (e) => ({ message: e.text, externalUserId: e.userId, externalMessageId: e.id }),
+  bind: (e) => ({ conversationId: e.conversationId }),
+  send: async (message, ctx) => {
+    // ctx.event is absent on a bound turn; ctx.handle always carries what bind() returned
+    const target = ctx.handle ?? { conversationId: ctx.event!.conversationId };
+    return { ref: await postToMySurface(target, message.text, ctx.previousRef) };
+  },
+});
+```
+
+`inbound` may return `{ message, externalUserId, externalMessageId }` as well as a plain string or `UIMessage`. The runtime stamps every channel-delivered user message with `metadata: { source: "channel", connectorId, provider, deliveryId, externalDeliveryId?, externalUserId?, externalMessageId? }` (`deliveryId` is the delivery's `whd_` id and `externalDeliveryId` the provider's), and a [transcript storage](/ai-chat/transcript-storage) receives `source: "channel"` and the `connectorId` on its save context, so a store you own can attribute and reconcile channel messages.
+
+## Files, buttons and steering
+
+Three more hooks cover what a chat surface carries besides text:
+
+- `download(url, { handle })` fetches files only the surface's credentials can read. Have `inbound` return file parts on the surface's URLs, and the `streamText` passed to `run()` asks each connector's `download` for every file URL in the prompt (return null for URLs it doesn't own). Downloads are cached for the run and the transcript keeps the URL. A file `download` throws on becomes a short note in that turn's messages, and the turn still runs.
+- `toAction(event)` maps a click on a control the agent posted to an action. It reaches `onAction`, validated against `actionSchema`, with the click itself as `channel.event`. Returning `chat.turn(message)` answers in the bound thread. Return null for anything else, such as a click answering a pending tool call, which `onInteraction` handles.
+- With [`pendingMessages`](/ai-chat/pending-messages) on the agent, a channel message that arrives while a turn is running goes through `inbound` and is offered to `shouldInject` like a browser message (its `metadata.source` is `"channel"`). Stops, clicks and empty messages are never offered.
+- `received(ctx)` acknowledges a channel message that arrives while a turn is running, as soon as it arrives and whether or not `pendingMessages` folds it in, so its wording should be true either way: `slack()` reacts with 👀, `linear()` posts a thought. Stops, clicks and empty messages are not acknowledged.
+
+## Channels vs events
+
+Both are inbound surfaces on a `chat.agent`, and an agent can list both:
+
+- [`events`](/webhooks/session-routing) (`chat.event`): the webhook is a signal. Delivered to `onAction`; the agent acts, no reply is sent back.
+- `channels` (`slack`, `chat.channels.custom`): the webhook is a chat frontend. Delivered as a turn to `run()`; the reply is posted back.

package/docs/webhooks/connect.mdx

@@ -0,0 +1,91 @@
+---
+title: "Connect a webhook provider"
+description: "Register an endpoint's URL and signing secret with the provider, by hand or with an AI coding agent, then check that events arrive."
+sidebarTitle: "Connect a provider"
+---
+
+Connect a provider to an [endpoint](/webhooks/overview) by registering the endpoint's URL with the provider and giving Trigger.dev the credential that verifies its requests.
+
+Deploy the project or start `trigger dev` first. Once the CLI finds the endpoint, it appears on the environment's **Webhooks** page. The **Signing secret** column shows **Ready** when the endpoint can verify deliveries and **Needs secret** until then. Every delivery is rejected while an endpoint needs its secret.
+
+## Set it up with an AI agent
+
+Each endpoint has a setup prompt: the URL, the events its subscribers filter on, the provider's own setup steps, and how to generate or store the signing secret. Choose **Copy setup prompt** on the Webhooks page or the endpoint's page, and paste it into an AI coding agent such as Claude Code.
+
+The prompt tells the agent to use the Trigger.dev MCP server (`npx trigger.dev@latest install-mcp`), which has these tools:
+
+| Tool | What it does |
+| --- | --- |
+| `list_webhook_endpoints` | Lists the environment's endpoints, with their URL and whether a secret is set. |
+| `get_webhook_endpoint_details` | Reads one endpoint: URL, subscribers and their filters, secret state, and the setup prompt. |
+| `generate_webhook_secret` | Generates a signing secret and returns it once, for providers where you choose the secret. Optionally keeps accepting the old secret (`previousSecretTtlSeconds`). |
+| `set_webhook_secret` | Stores a secret the provider issued. Optionally keeps accepting the old secret (`previousSecretTtlSeconds`). |
+
+Without the MCP server, the same operations are available on the REST API with the environment's secret key:
+
+| Request | What it does |
+| --- | --- |
+| [`GET /api/v1/webhooks/endpoints`](/management/webhooks/list-endpoints) | Lists the environment's endpoints, with their URL and whether a secret is set. |
+| [`GET /api/v1/webhooks/endpoints/{endpointId}`](/management/webhooks/retrieve-endpoint) | Reads the endpoint, including `subscribers` and `setupPrompt`. |
+| [`POST /api/v1/webhooks/endpoints/{endpointId}/rotate-secret`](/management/webhooks/generate-secret) | Generates a secret and returns it once. |
+| [`PUT /api/v1/webhooks/endpoints/{endpointId}/secret`](/management/webhooks/set-secret) | Stores a secret, sent as `{ "secret": "..." }`. |
+
+`endpointId` is the endpoint's declared id (the `id` passed to `webhooks.endpoint.define`) or its `wh_` id, shown on its page and returned by `list_webhook_endpoints`:
+
+```bash
+curl -X PUT "https://api.trigger.dev/api/v1/webhooks/endpoints/stripe/secret" \
+  -H "Authorization: Bearer $TRIGGER_SECRET_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"secret": "whsec_..."}'
+```
+
+## Set it up by hand
+
+<Steps>
+  <Step title="Copy the webhook URL">
+    Open the endpoint from the Webhooks page and copy the **Webhook URL**.
+  </Step>
+  <Step title="Configure the provider">
+    Add the URL as the webhook destination in your provider's dashboard and select the events your subscribers need. The provider's setup determines where the verification credential comes from:
+
+    | Provider setup | Action |
+    | --- | --- |
+    | The provider supplies a signing secret, as Stripe and Svix do | Copy the secret from the provider, then choose **Set signing secret** on the endpoint. |
+    | The provider accepts a secret you choose, as GitHub does | Choose **Generate secret** on the endpoint, then paste the value into the provider's webhook configuration. |
+    | The provider uses an asymmetric signature, as Discord does | Copy the application's public key from the provider and choose **Set public key** on the endpoint. |
+
+    Set the credential before sending a test event or asking the provider to validate the URL.
+  </Step>
+</Steps>
+
+## Verify the connection
+
+Send a test event from your provider, or use the endpoint's **Test** tab. The event appears on the endpoint's **Deliveries** tab. Open it to see which subscribers it reached and follow the links to their runs; see [Deliveries and endpoints](/webhooks/deliveries) for the statuses.
+
+If no delivery appears, check that the provider uses the copied URL and that both sides have the same signing secret or public key.
+
+## Verify a WhatsApp endpoint URL
+
+`webhooks.whatsapp()` also needs a verify token for Meta's URL check. On the endpoint, choose **Generate verify token** and paste the value into Meta's **Verify Token** field. Set Meta's App Secret as the signing secret, then validate the URL in Meta's dashboard.
+
+The verify token answers the URL check. The signing secret verifies event deliveries. See [Sources and verification](/webhooks/sources#endpoint-validation) for the response behavior.
+
+## Rotate a credential
+
+Choose **Rotate signing secret** to replace a provider-supplied secret. For a secret you generate, choose **Regenerate secret**, copy the new value, and update the provider's configuration. Use **Rotate public key** when replacing an asymmetric provider's key.
+
+Both dialogs ask how long to keep accepting the old secret: **Stop immediately**, 1 hour, 24 hours (the default) or 7 days. Until then, deliveries signed with either secret verify, so you can update the provider without failing any. Choose **Stop immediately** if the old secret leaked.
+
+Through the MCP tools or the REST API, pass `previousSecretTtlSeconds` (at most 604800, 7 days). The response's `previousSecretExpiresAt` says when the old secret stops working. Without it, the old secret stops working straight away:
+
+```bash
+curl -X POST "https://api.trigger.dev/api/v1/webhooks/endpoints/github/rotate-secret" \
+  -H "Authorization: Bearer $TRIGGER_SECRET_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"previousSecretTtlSeconds": 3600}'
+```
+
+<Warning>
+  Trigger.dev stores credentials encrypted and doesn't display saved values. Copy a generated secret
+  before closing the dialog.
+</Warning>

package/docs/webhooks/deliveries.mdx

@@ -0,0 +1,99 @@
+---
+title: "Deliveries and endpoints"
+description: "Inspect webhook payloads, where each delivery went, and the runs it started or resumed."
+sidebarTitle: "Deliveries and endpoints"
+---
+
+**A delivery records a verified webhook event and what happened to it at each subscriber.** Find deliveries on an endpoint's **Deliveries** tab. A run that a delivery triggered links back to it, and to its endpoint, from the run's **Detail** tab.
+
+## Endpoints
+
+The environment's **Webhooks** page lists its endpoints with their URL, whether the signing secret is set, the last 24 hours of activity, and the last delivery. Open an endpoint for its tabs:
+
+| Tab | Shows |
+| --- | --- |
+| **Deliveries** | The endpoint's deliveries, filterable by status and time. |
+| **Subscribers** | Every task, agent session and channel subscribed to the endpoint, with each one's filter. |
+| **Waiters** | Runs currently [waiting](/webhooks/waiters) on the endpoint. |
+| **Test** | Sends a sample event through the endpoint. |
+
+The endpoint's details show its URL, source, verification scheme and signing secret actions. See [Connect a provider](/webhooks/connect).
+
+### Disable an endpoint
+
+Disable an endpoint to stop accepting its deliveries without removing it from your code. Its status becomes `inactive` and its URL responds with `404`, so the provider records failed deliveries and retries them on its own schedule:
+
+```bash
+curl -X POST "https://api.trigger.dev/api/v1/webhooks/endpoints/stripe/disable" \
+  -H "Authorization: Bearer $TRIGGER_SECRET_KEY"
+```
+
+[Enable](/management/webhooks/enable-endpoint) it again with `POST /api/v1/webhooks/endpoints/{endpointId}/enable`. An endpoint that is no longer in the environment's current deployment is also `inactive`.
+
+## Delivery status
+
+| Status | Meaning |
+| --- | --- |
+| `PENDING` | Waiting to be routed, including after a retryable error at a subscriber. |
+| `PROCESSING` | Being routed. A delivery that resumes many waiting runs stays here until they have all been resumed. |
+| `SUCCEEDED` | At least one subscriber or waiting run received it, and nothing failed. |
+| `FAILED` | A subscriber failed after its retries. The delivery's error names it. |
+| `FILTERED` | No subscriber's filter matched, or the endpoint has no subscribers. The reason shows the failed clause. |
+| `UNMATCHED` | Runs were waiting on the endpoint, but none matched and no subscriber took it. |
+
+Delivery status tracks routing. Each run it started has its own status and retry history.
+
+## Where a delivery went
+
+Open a delivery to see its payload and headers, and a row per subscriber with its result (`SUCCEEDED`, `FILTERED` with the reason, or `FAILED` with the error) and a link to the run it started. Waiting runs are summarized in one row: how many waiters matched, how many were resumed, and how many failed to resume.
+
+A subscriber that fails transiently is retried on its own; subscribers that already succeeded are not run again.
+
+## Replay
+
+Replaying a delivery routes its event again as a new delivery. Filters are checked again, so the replay reaches the subscribers that would take the event now:
+
+```bash
+curl -X POST "https://api.trigger.dev/api/v1/webhooks/deliveries/whd_1234/replay" \
+  -H "Authorization: Bearer $TRIGGER_SECRET_KEY"
+```
+
+Add `?targetId=` to send it to one subscriber regardless of its filter. `targetId` is the subscriber id: a `webhook()` task's id, or `agentId:eventId` for an agent's `chat.event` or channel. A replay never resumes waiting runs.
+
+## From an agent or the API
+
+The [MCP server](/mcp-introduction) has `list_webhook_deliveries` (filter by endpoint, status and time), `get_webhook_delivery` (each subscriber's result, the waiter summary, the event and headers) and `replay_webhook_delivery`. The same data is on the REST API:
+
+| Request | What it does |
+| --- | --- |
+| [`GET /api/v1/webhooks/deliveries`](/management/webhooks/list-deliveries) | Lists deliveries, newest first. Filter with `filter[endpoint]` (declared or `wh_` ids), `filter[status]`, and `filter[period]` or `filter[from]`/`filter[to]`. |
+| [`GET /api/v1/webhooks/deliveries/{deliveryId}`](/management/webhooks/retrieve-delivery) | Reads a delivery, with a `targets` entry per subscriber and one for waiting runs. |
+| [`POST /api/v1/webhooks/deliveries/{deliveryId}/replay`](/management/webhooks/replay-delivery) | Replays it, as above. The key needs permission to trigger every task the replay starts, and to write sessions if it reaches an agent's subscriber. |
+
+## Deduplication
+
+Trigger.dev uses the endpoint and idempotency key to deduplicate incoming events. Delivery records and task runs have separate deduplication windows:
+
+| What is deduplicated | Window |
+| --- | --- |
+| Delivery records | Six hours by default. |
+| Task runs | Three days for Stripe; one day for other sources. |
+
+A retry after the delivery window expires can create another delivery record. If the task-run idempotency window is still active, routing returns the existing run instead of starting another one.
+
+When the source maps a provider event ID, that ID becomes the key, so the provider's own retries of an event are recognised as duplicates:
+
+| Key | Sources |
+| --- | --- |
+| A header | GitHub (`X-GitHub-Delivery`), Svix and Autumn (`svix-id`), Standard Webhooks, Loops and Granola (`webhook-id`), Linear (`Linear-Delivery`), PagerDuty (`X-Webhook-Id`), Jira (`X-Atlassian-Webhook-Identifier`), Zendesk (`X-Zendesk-Webhook-Invocation-Id`), Attio (`Idempotency-Key`), Shopify (`X-Shopify-Webhook-Id`), Hookdeck (`X-Hookdeck-Eventid`, or `<prefix>-eventid` with a custom header prefix) |
+| A body field | Stripe, Notion, Vercel, Intercom, WorkOS, Metronome, Mux, Langfuse and Plain (`id`), Square, Slack and Typeform (`event_id`), Firecrawl (`webhookId`) |
+
+The other named sources (Zoom, Calendly, Sentry, DocuSign, ElevenLabs, Vapi, Retell, Tailscale, Infisical, PlanetScale, Supabase, Discord) use the fallback below.
+
+If the source doesn't map an event ID, the key is derived from the raw body, timestamp, and signature. A retry with a different timestamp or signature can therefore produce a different key. For a [custom source](/webhooks/sources#custom-providers), set `idempotencyField` to a stable event identifier when the provider supplies one.
+
+## Verification and recording
+
+Requests must pass the source's verification checks before they are recorded. Timestamp checks apply when configured by the source. A verification failure returns the source's rejected HTTP status (`400` by default) and creates no delivery or run.
+
+Provider handshakes receive their configured response without creating a delivery. Other verified events are checked for duplicates, recorded, and routed. Filtered and unmatched deliveries stay visible, so you can see what arrived and why nothing ran.

package/docs/webhooks/filters.mdx

@@ -0,0 +1,146 @@
+---
+title: "Filtering deliveries"
+description: "Choose which verified webhook events reach each subscriber, by payload fields, request headers, or endpoint metadata."
+sidebarTitle: "Filters"
+---
+
+**A filter selects which verified deliveries reach a subscriber.** Each subscriber on an [endpoint](/webhooks/overview) has its own filter, so one delivery can start one task and skip another. A delivery no subscriber takes is recorded with status `FILTERED`, so you can inspect it in the dashboard.
+
+## Add a filter
+
+Set `filter` on the subscriber. This example accepts Stripe payment-intent events whose amount is at least 10,000:
+
+```ts /trigger/payment-events.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const stripe = webhooks.endpoint.define({ id: "stripe", source: webhooks.stripe() });
+
+export const largePayments = webhook({
+  id: "large-payments",
+  endpoint: stripe,
+  filter: "event.type == 'payment_intent.succeeded' && event.data.object.amount >= 10000",
+  onEvent: async ({ event }) => {
+    console.log("Matched payment event", event.id);
+  },
+});
+```
+
+The same `filter` works on a [`chat.event`](/webhooks/session-routing#filtering), a channel connector, and a [waiter](/webhooks/waiters), where it is checked after the waiter's `match`.
+
+The filter is checked against the [endpoint's event type](/webhooks/sources#typing-the-event). Concrete types catch missing fields and incompatible literals. Fields typed as `unknown`, including values in Stripe's default `data.object`, allow arbitrary non-empty field paths. Operator literals and path structure are still checked. A filter built at runtime (typed as `string` rather than a string literal) skips the compile-time check, and is validated when the endpoint is deployed.
+
+## Narrow a union event
+
+When the endpoint's event is a union, such as `webhooks.stripe<Stripe.Event>()`, an `event.<field> == '<value>'` clause selects the members whose field can hold that value. The rest of that `&&` chain is checked against those members, and the handler's `event` has their type:
+
+```ts /trigger/checkouts.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+import type Stripe from "stripe";
+
+export const stripe = webhooks.endpoint.define({
+  id: "stripe",
+  source: webhooks.stripe<Stripe.Event>(),
+});
+
+export const checkouts = webhook({
+  id: "checkouts",
+  endpoint: stripe,
+  filter: "event.type == 'checkout.session.completed' && event.data.object.amount_total >= 100",
+  onEvent: async ({ event }) => {
+    const session: Stripe.Checkout.Session = event.data.object; // no cast needed
+    console.log("Checkout completed", session.id);
+  },
+});
+```
+
+- `in [...]` selects the members for any listed value, and `||` gives the union of its branches. Parentheses group branches as usual.
+- `!=`, `not in`, numeric comparisons, string operators, and `any`/`all` don't narrow. Neither do `null`, `'null'`, or `0`, because the server's `==` also matches a null field for those values.
+- Without a type clause, a field that only some members have is accepted: an event without it never matches.
+- The narrowed type also applies to the task's trigger payload, a `chat.event` action's `event` and `key`, channel connector callbacks, and a waiter's event. A filter built at runtime doesn't narrow.
+
+## Check the result
+
+Send an event and open its [delivery](/webhooks/deliveries) in the dashboard. Each subscriber's row shows whether it took the event, and a filtered subscriber shows the failed clause and its value. The provider receives the source's accepted HTTP status (`200` by default) either way.
+
+<Note>
+  If filter evaluation throws an exception, Trigger.dev routes the event. Filters aren't a substitute
+  for signature verification or validation inside your handler.
+</Note>
+
+## The expression language
+
+A filter is one or more `path operator value` clauses combined with `&&` and `||` (use parentheses to group).
+
+### Paths
+
+A path reads from one of three namespaces:
+
+- `event.*`: the verified, parsed request body, for example `event.data.object.amount`.
+- `header.*`: an inbound request header, matched case-insensitively, for example `header.x-github-event`.
+- `webhook.*`: endpoint and delivery metadata: `source`, `id`, `deliveryId`, `externalRef`, and `tenantId`. The last two depend on the endpoint configuration.
+
+Paths must have non-empty segments. `event.data.amount` is valid; `event.`, `event..amount`, and `event.amount.` are rejected.
+
+[Session routing](/webhooks/session-routing) keys use the same namespaces in braces (`{event.data.object.customer}`), and [waiter](/webhooks/waiters) `match` paths use them as keys (`"event.data.object.metadata.orderId"`).
+
+### Operators
+
+| Operator | Meaning |
+| --- | --- |
+| `==` `!=` | equality |
+| `>` `<` `>=` `<=` | numeric comparison |
+| `in` `not in` | membership in a list, for example `event.type in ['a', 'b']` |
+| `startsWith` `endsWith` `contains` | string matching |
+
+Values are strings in single quotes (`'created'`), numbers (`10000`), booleans (`true`), or `null`. Use a list of these values with `in` and `not in`.
+
+A `null` value checks presence. `event.issue.pull_request != null` matches events that have the field, and `== null` matches events where it is missing or `null`. It works on any field, including fields your event type marks as required, because a missing field compares equal to `null`.
+
+### Comparing two fields
+
+Equality and comparison operators also accept a field path on the right-hand side:
+
+```text Filter expression
+event.billing.country == event.shipping.country
+```
+
+### Matching inside a list
+
+`any` matches if at least one array element meets the condition. `all` requires every element to match. The path inside the parentheses is relative to each element:
+
+```text Filter expression
+event.items any ( quantity > 0 )
+```
+
+When the payload itself is an array, as with providers that batch several events into one request (Tailscale, for example), quantify over `event`:
+
+```text Filter expression
+event any ( type == 'nodeCreated' )
+```
+
+### Spacing
+
+Separate paths, operators, and values with one space. Parentheses may touch what they enclose, as in `(event.amount > 0)` and `any (quantity > 0)`. Lists and quoted strings may contain spaces (`['opened', 'closed']`, `'Fix the build'`). These forms work with both the TypeScript validator and the deployment parser.
+
+## Filter by event type
+
+Use the field or header your provider supplies for its event type. GitHub uses the `x-github-event` header:
+
+```ts /trigger/github-events.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const github = webhooks.endpoint.define({ id: "github", source: webhooks.github() });
+
+export const onIssuesAndPullRequests = webhook({
+  id: "github-issues-and-prs",
+  endpoint: github,
+  filter: "header.x-github-event in ['issues', 'pull_request']",
+  onEvent: async ({ headers }) => {
+    console.log("Matched GitHub event", headers.get("x-github-event"));
+  },
+});
+```
+
+## Filtering a session route
+
+A `filter` works the same way on [`chat.event`](/webhooks/session-routing): a delivery that doesn't match never reaches the session.

package/docs/webhooks/human-in-the-loop.mdx

@@ -0,0 +1,158 @@
+---
+title: "Human-in-the-loop"
+sidebarTitle: "Human-in-the-loop"
+description: "Pause an agent mid-turn to get a human decision from the channel (Slack approve/deny), then resume with the answer."
+---
+
+**An agent on a [channel](/webhooks/channels) can pause a turn to get a human decision, then resume once someone answers in the thread.** It posts controls into the conversation and picks up where it left off once someone clicks, with the decision merged into the turn. This is the channel counterpart of browser [human-in-the-loop](/ai-chat/patterns/human-in-the-loop): the same no-`execute` tool, but the controls live in Slack (or your own surface) instead of a React component. The [`slack()`](/webhooks/slack) connector ships Approve and Deny buttons out of the box.
+
+## How it works
+
+The building block is a tool with no `execute` function. When the model calls it, the turn completes with the tool call still pending instead of resolving it. Over a channel the framework then takes over the round-trip:
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant S as Slack
+    participant A as Agent run
+    U->>S: Message in a thread
+    S->>A: Verified delivery starts a turn
+    A->>A: Model calls requestApproval (no execute)
+    A->>S: renderInteraction posts Approve and Deny
+    Note over A: Turn completes, run suspends (no compute while waiting)
+    U->>S: Clicks a button
+    S->>A: Signed block_actions callback to the same webhook URL
+    A->>A: onInteraction resolves the pending tool
+    A->>S: finalizeInteraction collapses the buttons
+    A->>A: Run resumes, model continues
+    A->>S: Reply posts back to the thread
+```
+
+Because it is a no-`execute` pause, the run suspends while it waits rather than holding compute. A human can take minutes or days to decide without burning compute or hitting [`maxDuration`](/runs/max-duration). The mechanics are the same as the browser case, covered in [human-in-the-loop](/ai-chat/patterns/human-in-the-loop#duration-and-cost-while-paused).
+
+## Slack approvals
+
+Out of the box, `slack()` posts Approve and Deny buttons for any pending no-`execute` tool. A click resolves to `{ approved: boolean }` and the buttons collapse to the decision. You define the tool and list the channel on the agent:
+
+```ts trigger/support-agent.ts
+import { webhooks } from "@trigger.dev/sdk";
+import { chat } from "@trigger.dev/sdk/ai";
+import { appMentions, slack, webhookSource } from "@trigger.dev/slack";
+import { tool } from "ai";
+import { anthropic } from "@ai-sdk/anthropic";
+import { z } from "zod";
+
+const slackEvents = webhooks.endpoint.define({ id: "slack", source: webhookSource() });
+
+// No execute: calling this pauses the turn for a human decision.
+const requestApproval = tool({
+  description:
+    "Request human approval before a sensitive or irreversible action. " +
+    "Call this and stop; you will receive { approved: boolean }, then proceed or decline.",
+  inputSchema: z.object({
+    action: z.string().describe("A short description of the action needing approval"),
+  }),
+});
+
+export const supportAgent = chat.agent({
+  id: "support-agent",
+  channels: [
+    slack({
+      id: "support-slack",
+      endpoint: slackEvents,
+      token: process.env.SLACK_BOT_TOKEN!,
+      startOn: appMentions(),
+    }),
+  ],
+  tools: { requestApproval },
+  run: async ({ messages, tools, streamText }) =>
+    streamText({
+      model: anthropic("claude-sonnet-4-5"),
+      messages,
+      tools,
+      system:
+        "Before any sensitive or irreversible action (refunds, cancellations, deletions), " +
+        "call requestApproval and wait. If approved, confirm it is done; if denied, decline.",
+    }),
+});
+```
+
+Button clicks arrive through Slack's interactivity, so the app needs **Interactivity & Shortcuts** turned on with the Request URL set to the **same** endpoint URL as events. The [Slack agents](/webhooks/slack#setup) manifest already does this.
+
+When the model calls `requestApproval`, the bot posts "Approval needed" with the action and Approve and Deny buttons, and the session's status is **suspended**. Clicking **Approve** resolves the tool to `{ approved: true }`, the buttons collapse to "Approved by @you", and the agent continues and streams the outcome. **Deny** resolves `{ approved: false }`. Pressing Slack's stop button instead cancels the approval: the buttons are replaced with "Stopped" and a later click resumes nothing.
+
+## Customizing the controls
+
+For [`chat.channels.custom`](/webhooks/channels), four hooks own the interaction round-trip:
+
+<ParamField body="renderInteraction" type="(pending, ctx) => ChannelMessage | null">
+  Map the pending tool call(s) to the controls you post. `pending` is a list of `{ toolCallId, toolName, input }`, and `ctx` carries the `event` and `deliveryId` that started the turn (both absent on a bound turn, such as a `chat.turn()` action answering into the thread). Return `null` to skip posting controls.
+</ParamField>
+
+<ParamField body="onInteraction" type="(event) => { toolCallId, output } | null">
+  Map a verified callback event to a resolution. The `output` is stitched onto the pending tool call matched by `toolCallId` and the run resumes. Return `null` to treat the event as a normal message instead (a new turn).
+</ParamField>
+
+<ParamField body="finalizeInteraction" type="(event, resolution) => void">
+  Collapse the controls after a decision so they cannot be clicked again. Best effort: a failure here is logged and the run still resumes.
+</ParamField>
+
+<ParamField body="cancelInteraction" type="(cancelled, ctx) => void">
+  Take the controls down when a stop (`onControl` returning `{ kind: "stop", whenIdle: "drop" }`) arrives while the session waits on them. Each cancelled call carries the `ref` its controls were posted with. The calls are already resolved as stopped. Best effort: a failure is logged.
+</ParamField>
+
+Slack encodes the tool call id and the click's output in each button's `value` so `onInteraction` can resolve the exact call (see [Approvals and buttons](/webhooks/slack#approvals-and-buttons) to customize the buttons or give a tool its own UI), and `finalizeInteraction` posts to the interaction's `response_url` with `replace_original` to swap the buttons for the outcome. On a custom surface you choose the encoding and how you edit the controls away.
+
+```ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { webhooks } from "@trigger.dev/sdk";
+
+const surface = webhooks.endpoint.define({
+  id: "my-surface",
+  source: webhooks.custom<MyEvent>({ /* verifier config */ }),
+});
+
+chat.channels.custom({
+  id: "my-surface",
+  endpoint: surface,
+  key: "{event.conversationId}",
+  inbound: (e) => e.text,
+  send: async (message, ctx) => ({ ref: await postToMySurface(ctx.event, message) }),
+  renderInteraction: (pending) => ({
+    text: `Approve: ${pending[0].input.action}?`,
+    buttons: pending.map((c) => [`${c.toolCallId}:yes`, `${c.toolCallId}:no`]),
+  }),
+  // called for every delivery: return null for anything that isn't one of these button clicks
+  onInteraction: (e) => {
+    if (typeof e.buttonValue !== "string" || !e.buttonValue.includes(":")) return null;
+    const [toolCallId, choice] = e.buttonValue.split(":");
+    return { toolCallId, output: { approved: choice === "yes" } };
+  },
+  finalizeInteraction: async (e) => {
+    await editMySurface(e.messageRef, "Decision recorded");
+  },
+});
+```
+
+The resolved `output` is whatever your tool expects to receive. The Slack default resolves `{ approved: boolean }`; if your tool needs a richer answer, supply your own `onInteraction` that returns the shape your tool reads.
+
+## The reply after a decision
+
+When the turn resumes, the channel reply shows the agent's answer, not the text it produced before pausing. The framework posts the assistant text generated after the tool call, so a preamble like "I'll need approval first" is not concatenated onto the final "done" message. The approval prompt itself already lives in the collapsed controls.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Channels" icon="comments" href="/webhooks/channels">
+    Point Slack or any surface at an agent so messages become turns.
+  </Card>
+  <Card title="Browser human-in-the-loop" icon="hand" href="/ai-chat/patterns/human-in-the-loop">
+    The same no-execute pause, rendered in a React frontend.
+  </Card>
+  <Card title="Sessions" icon="layer-group" href="/ai-chat/sessions">
+    The durable per-conversation state a channel turn runs on.
+  </Card>
+  <Card title="Filters" icon="filter" href="/webhooks/filters">
+    Gate which verified deliveries reach the agent.
+  </Card>
+</CardGroup>