docs(webhooks): publish the webhooks private beta docs

Mono-RevId: bb6728e6f219c8de7fd58500bb0629e311aecea4

Author: ericallam

.claude/rules/docs-writing.md

@@ -14,7 +14,7 @@ paths:
 - Link to related pages using relative paths (e.g., `[Tasks](/tasks/overview)`).
 - Features behind a flag that isn't fully on:
   - Dark (nobody outside the team has it): don't write docs yet.
-  - Private beta or rolling out: put the docs in the feature PR with `<PrivateBeta flag="<key>" />` or `<RollingOut flag="<key>" />` (import from `/snippets/feature-status.jsx`), at the top of the page or the section. Use `flag="env:<NAME>"` for env-var gates. Keep it on one line with string values.
+  - Private beta or rolling out: put the docs in the feature PR with `<PrivateBeta flag="<key>" />` or `<RollingOut flag="<key>" />` (import from `/snippets/feature-status.jsx`), at the top of the page or the section. Use `flag="env:<NAME>"` for env-var gates. Keep the opening tag on one line with string values. To add page-specific text (how to get access, say), put it inside the tag: `<PrivateBeta flag="<key>">...</PrivateBeta>`; it renders after the fixed line.
   - The PR that removes the flag also removes the callout. CI fails while a callout points at a missing flag.
   - Avoid two callouts in a row. A `<PrivateBeta>` or `<RollingOut>` callout next to another callout is the one exception, because it's temporary. Leave the existing callout as it is.
   - Only for flags that cloud rolls out. Never add it to self-host config docs.

docs/ai-chat/actions.mdx

@@ -73,11 +73,16 @@ onAction: async ({ action }) => {
       chat.history.slice(0, -1);
       chat.inject([{ role: "system", content: "Answer formally this time." }]);
       return chat.turn(); // with a one-shot instruction
+
+    case "ask":
+      return chat.turn(action.question); // answer a new user message
   }
 }
 ```
 
-`run()` receives the edited history with no incoming user message, the same shape as a `regenerate-message` turn, and its `trigger` is `"action-turn"`, so a `run()` that returns early on `"action"` (the pre-May behaviour, when actions invoked `run()` directly) still answers. Returning anything other than `chat.turn()` or nothing is an error; a response can no longer be returned from `onAction` directly.
+`chat.turn(message)` appends `message` (a string, or a `UIMessage`) to the history as a user message after the edit, and the turn answers it. That is how a button click becomes a question, such as a follow-up suggestion in [Slack](/webhooks/slack#buttons-that-send-the-agent-an-action).
+
+Without a message, `run()` receives the edited history with no incoming user message, the same shape as a `regenerate-message` turn, and its `trigger` is `"action-turn"`, so a `run()` that returns early on `"action"` (the pre-May behaviour, when actions invoked `run()` directly) still answers. Returning anything other than `chat.turn()` or nothing is an error; a response can no longer be returned from `onAction` directly.
 
 ### Actions and persistence
 

docs/ai-chat/backend.mdx

@@ -4,6 +4,8 @@ sidebarTitle: "Backend"
 description: "Three approaches to building your chat backend — chat.agent(), session iterator, or raw task primitives."
 ---
 
+import WebhooksBetaNote from "/snippets/webhooks-beta-note.mdx";
+
 There are three abstraction levels for a chat backend. All three speak the same wire protocol, so the [frontend transport](/ai-chat/frontend) works unchanged whichever you pick.
 
 | Capability                            | `chat.agent()` | `chat.createSession()`                                        | Raw primitives |
@@ -497,6 +499,44 @@ Custom actions let the frontend send structured commands (undo, rollback, edit,
 
 See [Actions](/ai-chat/actions).
 
+### Webhook events and channels
+
+<WebhooksBetaNote />
+
+Two `chat.agent()` options wire an agent to verified inbound webhooks. `events` claims [`chat.event(...)`](/webhooks/session-routing) descriptors: each verified delivery is routed to this agent's session and arrives at `onAction` as an action (not a turn), so [session routing](/webhooks/session-routing) decides which conversation it lands on. `channels` claims channel connectors that turn an external chat surface into a frontend for the agent: an inbound message runs as a turn through `run()` and the reply is posted back. `slack()` ships in `@trigger.dev/slack`, and `chat.channels.custom(...)` builds a connector for any endpoint without a preset.
+
+```ts
+import { webhooks } from "@trigger.dev/sdk";
+import { chat } from "@trigger.dev/sdk/ai";
+import { slack, webhookSource } from "@trigger.dev/slack";
+
+const slackEvents = webhooks.endpoint.define({ id: "slack", source: webhookSource() });
+const stripe = webhooks.endpoint.define({ id: "stripe", source: webhooks.stripe() });
+
+export const orderEvents = chat.event({
+  id: "order-events",
+  endpoint: stripe,
+  key: "{event.data.object.customer}",
+  // invoices always carry a customer; events without one would have no session to go to
+  filter: "event.type startsWith 'invoice.'",
+  type: "order.event",
+});
+
+export const myChat = chat.agent({
+  id: "my-chat",
+  events: [orderEvents],
+  channels: [slack({ id: "support-slack", endpoint: slackEvents, token: process.env.SLACK_BOT_TOKEN! })],
+  onAction: async ({ action }) => {
+    // A verified order-events delivery arrives here as an action.
+  },
+  run: async (payload) => {
+    // Inbound Slack messages run here as normal turns.
+  },
+});
+```
+
+See [session routing](/webhooks/session-routing) and [channels](/webhooks/channels). For the interactive approvals layer, where a turn pauses on a human decision (buttons in the thread) and resumes on the click, see [human-in-the-loop](/webhooks/human-in-the-loop).
+
 ### Chat history
 
 Imperative API for reading and modifying the accumulated message history. Works from any hook (`onAction`, `onTurnStart`, `onBeforeTurnComplete`, `onTurnComplete`, `hydrateMessages`) or from `run()` and AI SDK tools.

docs/ai-chat/pending-messages.mdx

@@ -12,6 +12,8 @@ By default (without `pendingMessages`), a message sent while the agent is respon
 
 The `pendingMessages` option enables steering instead, injecting user messages between tool-call steps via the AI SDK's `prepareStep`. Messages that arrive during streaming are queued and injected at the next step boundary. A message that is not injected becomes the next turn instead, whether that is because `shouldInject` returned `false` or because there were no more step boundaries (single-step response or final text generation). The backend handles that, so no client-side re-send is involved.
 
+Messages from a [channel](/webhooks/channels) such as [Slack](/webhooks/slack) are offered the same way, with `metadata.source` set to `"channel"` so `shouldInject` can tell them apart. A channel's stop control and approval clicks are never offered. The connector acknowledges a channel message as soon as it arrives (Slack reacts with 👀, Linear posts a thought), before `shouldInject` decides, so the acknowledgement is the same whether the message is folded in or answered next. Channels are part of the [webhooks private beta](https://trigger.dev/webhooks-beta).
+
 Use the `streamText` passed to your agent's `run` callback. It wires up pending-message injection automatically. If you import `streamText` directly from `ai`, spread `chat.toStreamTextOptions()` into its options to connect injection.
 
 ## How it works

docs/ai-chat/reference.mdx

@@ -47,7 +47,9 @@ Options for `chat.agent()`.
 | `storage`                     | `TranscriptStorage`                                         | `defaultStorage`               | Where the conversation is persisted and read back. The platform snapshot by default; bring your own to write each change to your database. See [Transcript storage](/ai-chat/transcript-storage) |
 | `hydrateMessages`             | `(event: HydrateMessagesEvent) => UIMessage[] \| Promise<UIMessage[]>` | —                 | **Deprecated.** Load message history from backend, replacing the linear accumulator. Use `loadContext` on a `storage` instead; cannot be combined with `storage`. See [hydrateMessages](/ai-chat/lifecycle-hooks#hydratemessages) |
 | `actionSchema`                | `TaskSchema`                                                | —                              | Schema for validating custom actions sent via `transport.sendAction()`. See [Actions](/ai-chat/actions) |
-| `onAction`                    | `(event: ActionEvent) => Promise<void \| ActionTurn> \| void \| ActionTurn` | —                              | Handle custom actions. Actions are state edits: only `hydrateMessages` (or a storage's `loadContext`) + `onAction` fire. Return `chat.turn()` to run a turn on the edited history, or nothing for an edit only. See [Actions](/ai-chat/actions) |
+| `onAction`                    | `(event: ActionEvent) => Promise<void \| ActionTurn> \| void \| ActionTurn` | —                              | Handle custom actions. Actions are state edits: only `hydrateMessages` (or a storage's `loadContext`) + `onAction` fire. Return `chat.turn()` to run a turn on the edited history (`chat.turn(message)` to answer a new user message), or nothing for an edit only. See [Actions](/ai-chat/actions) |
+| `events`                      | `ChatEvent[]`                                               | —                              | Webhook event descriptors (from `chat.event()`) whose verified deliveries are routed to this agent as actions and handled in `onAction`. See [session routing](/webhooks/session-routing). Part of the [webhooks private beta](https://trigger.dev/webhooks-beta). |
+| `channels`                    | `ChannelConnector[]`                                        | —                              | Channel connectors (for example `slack()`) that turn an external chat surface into a frontend for the agent: inbound messages run as turns and the reply posts back. See [channels](/webhooks/channels). Part of the [webhooks private beta](https://trigger.dev/webhooks-beta). |
 | `onTurnStart`                 | `(event: TurnStartEvent) => Promise<void> \| void`          | —                              | Fires every turn before `run()`                                                                     |
 | `onBeforeTurnComplete`        | `(event: BeforeTurnCompleteEvent) => Promise<void> \| void` | —                              | Fires after response but before stream closes. Includes `writer`.                                   |
 | `onTurnComplete`              | `(event: TurnCompleteEvent) => Promise<void> \| void`       | —                              | Fires after each turn completes (stream closed)                                                     |
@@ -232,7 +234,7 @@ The persistence adapter set through `chat.agent({ storage })`. See [Transcript s
 | Type | Shape |
 | --- | --- |
 | `TranscriptScope<TClientData>` | `{ chatId: string; clientData: TClientData }` |
-| `TranscriptStorageContext<TClientData>` | `TranscriptScope` plus `{ turn: number; trigger: "submit-message" \| "regenerate-message" \| "action"; runId: string; ctx: TaskRunContext }` |
+| `TranscriptStorageContext<TClientData>` | `TranscriptScope` plus `{ turn: number; trigger: "submit-message" \| "regenerate-message" \| "action" \| "action-turn"; source?: "client" \| "channel" \| "webhook"; connectorId?: string; runId: string; ctx: TaskRunContext }`. `action-turn` is the turn `chat.turn()` requested; `source` names the surface that drove the write |
 | `TranscriptChange` | `{ op: "put"; message: UIMessage; final?: boolean }` \| `{ op: "remove"; id: string }` \| `{ op: "truncateAfter"; afterId: string }` \| `{ op: "state"; value: unknown \| null }` |
 | `TranscriptChangeset` | `{ reason: "turn-complete" \| "turn-error" \| "action" \| "compaction" \| "recovery"; changes: TranscriptChange[]; transcript: TranscriptState; cursors?: TranscriptCursors }` |
 | `TranscriptState` | `{ entries: Array<{ id: string; final: boolean; message: UIMessage }>; state: unknown \| null }`: the whole conversation after the changeset's changes, for stores that write one document |
@@ -275,6 +277,7 @@ Passed to the `onAction` callback. See [Actions](/ai-chat/actions).
 | `clientData` | Typed by `clientDataSchema` | Custom data from the frontend                            |
 | `uiMessages` | `UIMessage[]`               | Accumulated UI messages (after hydration, if set)        |
 | `messages`   | `ModelMessage[]`            | Accumulated model messages (after hydration, if set)     |
+| `channel`    | `{ connectorId, provider, event, deliveryId }` | For a channel action (a button the agent posted, such as a Slack `slackButton()`): the verified click event. Absent otherwise |
 
 ## TurnStartEvent
 
@@ -538,6 +541,8 @@ All methods available on the `chat` object from `@trigger.dev/sdk/ai`.
 | Method                                      | Description                                                                                                                  |
 | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
 | `chat.agent(options)`                       | Create a chat agent                                                                                                          |
+| `chat.event(options)`                       | Declare an inbound webhook event descriptor an agent claims via `chat.agent({ events })`. See [session routing](/webhooks/session-routing). Part of the [webhooks private beta](https://trigger.dev/webhooks-beta). |
+| `chat.channels.custom(options)`             | Create a generic chat-frontend channel over any verified webhook source (you supply the egress). The `slack()` preset ships in `@trigger.dev/slack`. See [channels](/webhooks/channels). Part of the [webhooks private beta](https://trigger.dev/webhooks-beta). |
 | `chat.createSession(payload, options)`      | Create an async iterator for chat turns                                                                                      |
 | `chat.pipe(source, options?)`               | Pipe a stream to the frontend (from anywhere inside a task)                                                                  |
 | `chat.pipeAndCapture(source, options?)`     | Pipe and capture the response; returns `{ message, status, error }`                                                         |
@@ -570,6 +575,51 @@ All methods available on the `chat` object from `@trigger.dev/sdk/ai`.
 | `chat.withUIMessage(config?)`               | Returns a [ChatBuilder](/ai-chat/types#chatbuilder) with a fixed `UIMessage` subtype. See [Types](/ai-chat/types)            |
 | `chat.withClientData({ schema })`           | Returns a [ChatBuilder](/ai-chat/types#chatbuilder) with a fixed client data schema. See [Types](/ai-chat/types#typed-client-data-with-chatwithclientdata) |
 
+## `chat.event`
+
+Declare an inbound webhook event that an agent claims via [`events`](#chatagentoptions) on `chat.agent()`. It is a descriptor only, with no handler: it names the [endpoint](/webhooks/overview) it subscribes to, a `key` template that resolves each delivery to a durable [session](/ai-chat/sessions), and an optional `type` label (defaults to the descriptor `id`). Verified deliveries are routed to that session and arrive at `onAction` as a `{ type, event, source, headers, deliveryId, endpoint }` envelope, not as a chat turn. See [session routing](/webhooks/session-routing).
+
+```ts
+import { webhooks } from "@trigger.dev/sdk";
+import { chat } from "@trigger.dev/sdk/ai";
+
+export const stripe = webhooks.endpoint.define({ id: "stripe", source: webhooks.stripe() });
+
+export const orderEvents = chat.event({
+  id: "order-events",
+  endpoint: stripe,
+  key: "{event.data.object.customer}",
+  // invoices always carry a customer; events without one would have no session to go to
+  filter: "event.type startsWith 'invoice.'",
+  type: "order.event",
+});
+```
+
+## `chat.channels.custom`
+
+Create a generic chat-frontend channel on any [endpoint](/webhooks/overview), claimed via [`channels`](#chatagentoptions) on `chat.agent()`. You supply the session `key`, the `inbound` map from event to turn message, and your own `send` egress that posts the reply back, so the whole round-trip is under your control. Inbound messages run as normal turns and the reply is posted back. The `slack()` preset ships in `@trigger.dev/slack` and wires the egress for you. See [channels](/webhooks/channels), and the interactive approvals layer at [human-in-the-loop](/webhooks/human-in-the-loop).
+
+```ts
+import { webhooks } from "@trigger.dev/sdk";
+import { chat } from "@trigger.dev/sdk/ai";
+
+const surface = webhooks.endpoint.define({
+  id: "my-surface",
+  source: webhooks.custom<MyEvent>({ /* verifier config */ }),
+});
+
+export const mySurface = chat.channels.custom({
+  id: "my-surface",
+  endpoint: surface,
+  key: "{event.conversationId}",
+  inbound: (event) => event.text,
+  send: async (message, ctx) => {
+    const ref = await postToMySurface(ctx.event, message.text, ctx.previousRef);
+    return { ref };
+  },
+});
+```
+
 ## `chat.withUIMessage`
 
 Returns a [`ChatBuilder`](/ai-chat/types#chatbuilder) with a fixed `UIMessage` subtype. Chain `.withClientData()`, hook methods, and `.agent()`.

docs/docs.json

@@ -159,6 +159,22 @@
               }
             ]
           },
+          {
+            "group": "Webhooks",
+            "pages": [
+              "webhooks/overview",
+              "webhooks/sources",
+              "webhooks/connect",
+              "webhooks/deliveries",
+              "webhooks/filters",
+              "webhooks/waiters",
+              "webhooks/session-routing",
+              "webhooks/channels",
+              "webhooks/slack",
+              "webhooks/linear",
+              "webhooks/human-in-the-loop"
+            ]
+          },
           {
             "group": "Configuration",
             "pages": [
@@ -386,6 +402,22 @@
               "management/errors/unresolve"
             ]
           },
+          {
+            "group": "Webhooks API",
+            "pages": [
+              "management/webhooks/list-endpoints",
+              "management/webhooks/retrieve-endpoint",
+              "management/webhooks/enable-endpoint",
+              "management/webhooks/disable-endpoint",
+              "management/webhooks/generate-secret",
+              "management/webhooks/set-secret",
+              "management/webhooks/list-deliveries",
+              "management/webhooks/retrieve-delivery",
+              "management/webhooks/replay-delivery",
+              "management/webhooks/create-waiter",
+              "management/webhooks/cancel-waiter"
+            ]
+          },
           {
             "group": "Queues API",
             "pages": [

docs/management/webhooks/cancel-waiter.mdx

@@ -0,0 +1,4 @@
+---
+title: "Cancel a webhook waiter"
+openapi: "v3-openapi POST /api/v1/webhooks/waiters/{waiterId}/cancel"
+---

docs/management/webhooks/create-waiter.mdx

@@ -0,0 +1,4 @@
+---
+title: "Create a webhook waiter"
+openapi: "v3-openapi POST /api/v1/webhooks/endpoints/{endpointId}/waiters"
+---

docs/management/webhooks/disable-endpoint.mdx

@@ -0,0 +1,4 @@
+---
+title: "Disable a webhook endpoint"
+openapi: "v3-openapi POST /api/v1/webhooks/endpoints/{endpointId}/disable"
+---

docs/management/webhooks/enable-endpoint.mdx

@@ -0,0 +1,4 @@
+---
+title: "Enable a webhook endpoint"
+openapi: "v3-openapi POST /api/v1/webhooks/endpoints/{endpointId}/enable"
+---