@trigger.dev/sdk 4.7.3 → 4.8.0-webhooks.20261015065339

package/docs/self-hosting/env/supervisor.mdx

@@ -14,6 +14,7 @@ mode: "wide"
 | `OTEL_EXPORTER_OTLP_ENDPOINT`               | Yes      | —           | OTel exporter endpoint. Point at: `<webapp-url>/otel`       |
 | **Worker instance**                         |          |             |                                                             |
 | `TRIGGER_WORKER_INSTANCE_NAME`              | No       | random UUID | Worker instance name. Set to `spec.nodeName` on k8s.        |
+| `TRIGGER_WORKER_CELL_NAME`                  | No       | —           | Name of the worker cluster this supervisor serves. Stamped on each run it starts. |
 | `TRIGGER_WORKER_HEARTBEAT_INTERVAL_SECONDS` | No       | 30          | Worker heartbeat interval (seconds).                        |
 | **Workload API settings**                   |          |             |                                                             |
 | `TRIGGER_WORKLOAD_API_ENABLED`              | No       | true        | Enable workload API. Runs use this to perform actions.      |
@@ -63,6 +64,7 @@ mode: "wide"
 | **Failed pod handler**                      |          |             |                                                             |
 | `FAILED_POD_HANDLER_ENABLED`                | No       | true        | Enable failed pod handler.                                  |
 | `FAILED_POD_HANDLER_RECONNECT_INTERVAL_MS`  | No       | 1000 (1s)   | Failed pod handler reconnect interval (ms).                 |
+| `FAILED_POD_HANDLER_WATCH_TIMEOUT_SECONDS`  | No       | 300 (5m)    | How long the server keeps each failed pod watch open (s).   |
 | **Debug**                                   |          |             |                                                             |
 | `DEBUG`                                     | No       | false       | Enable debug logs.                                          |
 | `SEND_RUN_DEBUG_LOGS`                       | No       | false       | Send run debug logs to the platform.                        |

package/docs/self-hosting/env/webapp.mdx

@@ -44,6 +44,9 @@ mode: "wide"
 | `WHITELISTED_EMAILS`                             | No       | —                     | Whitelisted emails regex.                                                                                          |
 | `BLOCKED_EMAIL_DOMAINS`                          | No       | —                     | Comma-separated email domains that can't sign in or sign up, including their subdomains.                           |
 | `LOGIN_RATE_LIMITS_ENABLED`                      | No       | true                  | Enable rate limiting on magic-link login.                                                                          |
+| `MAGIC_LINK_SAME_BROWSER_REQUIRED`               | No       | true                  | Only accept a magic link opened in the browser that requested it. Set to false to allow opening it on another device.|
+| `TURNSTILE_SITE_KEY`                             | No       | —                     | Cloudflare Turnstile site key. With `TURNSTILE_SECRET_KEY`, adds a bot check to the magic-link sign-in form.       |
+| `TURNSTILE_SECRET_KEY`                           | No       | —                     | Cloudflare Turnstile secret key, used to verify the check on the server. Turnstile is off unless both keys are set.|
 | `AUTH_GITHUB_CLIENT_ID`                          | No       | —                     | GitHub client ID.                                                                                                  |
 | `AUTH_GITHUB_CLIENT_SECRET`                      | No       | —                     | GitHub client secret.                                                                                              |
 | `CSP_IMG_SRC_ALLOWLIST`                          | No       | —                     | Extra hosts the dashboard may load images from, e.g. an SSO or avatar host serving profile images. A comma-separated list of exact origins (`https://sso.example.com`); a wildcard host such as `https://*.example.com` is refused. |
@@ -98,6 +101,8 @@ mode: "wide"
 | `DEPLOY_REGISTRY_NAMESPACE`                      | No       | trigger               | Deploy registry namespace.                                                                                         |
 | `DEPLOY_REGISTRY_ECR_DEFAULT_REPOSITORY_POLICY`  | No       | —                     | Raw IAM policy JSON applied via SetRepositoryPolicy to every ECR repo created by the webapp. Use to grant cross-account pull access to EKS workers when the ECR account is separate from the cluster account. |
 | `DEPLOY_IMAGE_PLATFORM`                          | No       | linux/amd64           | Deploy image platform, same values as docker `--platform` flag.                                                    |
+| `DEPLOY_BASE_IMAGES`                             | No       | —                     | Base images every deploy must build on, as comma-separated `runtime=image@sha256:<digest>`. See [custom base images](/self-hosting/overview#custom-base-images). |
+| `DEPLOY_BUILD_BASE_IMAGES`                       | No       | —                     | Build-stage images, in the same format as `DEPLOY_BASE_IMAGES`. See [custom base images](/self-hosting/overview#custom-base-images). |
 | `DEPLOY_TIMEOUT_MS`                              | No       | 480000 (8m)           | Deploy timeout (ms).                                                                                               |
 | `DEPLOY_QUEUE_TIMEOUT_MS`                        | No       | 900000 (15m)          | Deploy queue timeout (ms).                                                                                         |
 | **Object store (S3)**                            |          |                       |                                                                                                                    |

package/docs/self-hosting/overview.mdx

@@ -100,6 +100,32 @@ All fields are optional. Partial overrides are supported:
 }
 ```
 
+## Custom base images
+
+Deploys build on the published `triggerdotdev/node` and `triggerdotdev/bun` Debian images. To require a different base for every deploy to your instance, such as a FIPS-validated or hardened Node image, set `DEPLOY_BASE_IMAGES` on the webapp (and optionally `DEPLOY_BUILD_BASE_IMAGES` for the build stage):
+
+```bash
+DEPLOY_BASE_IMAGES="node-26=registry.example.com/node-fips:26@sha256:<64-character-digest>"
+```
+
+Entries are comma-separated `runtime=image@sha256:<digest>`. The runtimes are `node-22`, `node-24`, `node-26` and `bun`, and every image must be pinned by digest. An invalid value prevents the webapp from starting. Projects with `runtime: "node"` in their config resolve to the current default Node runtime (`node-24` today), so set that key for them. With the Helm chart, set the variables through `webapp.extraEnvVars`.
+
+Runtimes with an entry build on that image; the others keep the published images. Deploys from CLI versions that cannot apply the images are rejected with an error asking to upgrade, and so are `--native-build`, `--local-bundle` and `--from-bundle` deploys. This is a self-hosting setting and does not apply to Trigger.dev Cloud.
+
+You own a custom base image. It must provide:
+
+- `node` on `PATH` at the runtime's major version (for `bun`, both `bun` and `node`, because the final stage starts the app with `dumb-init node`)
+- `busybox`, `ca-certificates`, `dumb-init`, `git` and `openssl`
+- a `node` user (a `bun` user for the Bun runtime)
+- glibc, so native modules built in the build stage load at runtime
+
+A `DEPLOY_BUILD_BASE_IMAGES` image needs everything the base image provides, plus `python3`, `make` and `g++`. Build extensions that add image instructions are replayed on it. Without an entry, the build stage uses the published build image, except for projects whose build extensions add image instructions: those build from your base image and install the toolchain with `apt-get`, so that base must be Debian-based. To avoid the published images entirely, set both variables.
+
+<Warning>
+  `image.pkgs` and build extensions that run `apt-get` (such as `aptGet` and `playwright`) assume a
+  Debian base. On other distributions, install those packages in your base image instead.
+</Warning>
+
 ## Community support
 
 It's dangerous to go alone! Join the self-hosting channel on our [Discord server](https://discord.gg/NQTxt5NA7s).

package/docs/tags.mdx

@@ -118,3 +118,9 @@ for await (const run of runs.list({ tag: "user_123456", status: ["COMPLETED"] })
   console.log(run.id, run.taskIdentifier, run.finishedAt, run.tags);
 }
 ```
+
+<Tip>
+  To follow runs with a tag as they change, use
+  [`runs.subscribeToRunsWithTag()`](/realtime/backend/subscribe) instead of polling `runs.list()`.
+  See [runs.list() best practices](/runs/list-best-practices).
+</Tip>

package/docs/tasks/scheduled.mdx

@@ -45,7 +45,7 @@ export const firstScheduledTask = schedules.task({
     //this can be undefined if you didn't provide one
     console.log(payload.externalId); //is a string or undefined
 
-    //the next 5 dates this task is scheduled to run
+    //the next 10 dates this task is scheduled to run
     console.log(payload.upcoming); //is an array of Date objects
   },
 });
@@ -58,14 +58,14 @@ You can see from the comments that the payload has several useful properties:
 - `timezone` - the timezone the schedule was registered with, defaults to "UTC". In IANA format, e.g. "America/New_York".
 - `scheduleId` - the id of the schedule that triggered the task
 - `externalId` - the external id you (optionally) provided when creating the schedule
-- `upcoming` - the next 5 times the task is scheduled to run
+- `upcoming` - the next 10 times the task is scheduled to run
 
 <Note>
   This task will NOT get triggered on a schedule until you attach a schedule to it. Read on for how
   to do that.
 </Note>
 
-Like all tasks they don't have timeouts, they should be placed inside a [/trigger folder](/config/config-file), and you [can configure them](/tasks/overview#defining-a-task).
+Like all tasks they have a [maxDuration](/runs/max-duration), they should be placed inside a [/trigger folder](/config/config-file), and you [can configure them](/tasks/overview#defining-a-task).
 
 You can set a [TTL](/runs#time-to-live-ttl) on a scheduled task to automatically expire runs that aren't dequeued in time. This is useful when a schedule fires while the previous run is still executing - rather than queueing up stale runs, they'll expire:
 
@@ -142,7 +142,7 @@ To use imperative schedules you need to do two things:
 
 ## Spreading runs with windows
 
-By default a schedule runs at its exact cron time. When many schedules share the same cron pattern, such as a daily `0 9 * * *`, they all fire at the same time and load your downstream systems as well as ours. A **window** spreads those runs out: each schedule is assigned a stable time within the window after its cron time, so the load is smoothed while each schedule keeps firing at a predictable, repeatable moment.
+When many schedules share the same cron pattern, such as a daily `0 9 * * *`, they all fire at the same time and load your downstream systems as well as ours. A **window** spreads those runs out: each schedule is assigned a stable time within the window after its cron time, so the load is smoothed while each schedule keeps firing at a predictable, repeatable moment. New schedules use a [60-minute window by default](#default-window).
 
 The assigned time is deterministic. A given schedule always lands at the same offset for a given interval, so runs don't jump around between occurrences. And you can always see exactly when the next run will start.
 
@@ -151,7 +151,7 @@ Set a `window` as either:
 - **An absolute duration** in whole minutes or hours, up to 24 hours: `"30m"`, `"2h"`, `"24h"`. Absolute windows are capped at the next cron time, so a run is never delayed past its following occurrence.
 - **A percentage** of the interval between runs: `"30%"`, `"100%"`. A `"50%"` window on an hourly schedule spreads runs across the first 30 minutes of each hour.
 
-Set `"0m"` (or `"0%"`) for no spreading — the run fires at its exact cron time.
+Set `"0m"` (or `"0%"`) for no spreading — the run fires at its exact cron time. This also overrides the [default window](#default-window).
 
 Declarative schedules set the window on the `cron` object:
 
@@ -184,6 +184,12 @@ const createdSchedule = await schedules.create({
   is the assigned time the run will actually start.
 </Note>
 
+### Default window
+
+New schedules get a default 60-minute window unless you set one, so each run starts at a stable time within the hour after its cron time. Like any absolute window, it's capped at the next cron time: a schedule that runs every 15 minutes is spread across those 15 minutes.
+
+To opt a new schedule out of the default window, set `window: "0m"`.
+
 ### Free-plan minimum window
 
 Schedules created while an organization is on a free plan run no more than once per hour and use a minimum 60-minute window.

package/docs/triggering.mdx

@@ -746,6 +746,12 @@ await myTask.batchTrigger([{ payload: { some: "data" }, options: { delay: "1h" }
   manually, convert Dates to ISO strings first (e.g., `date.toISOString()`).
 </Note>
 
+<Tip>
+  A `delay` doesn't merge triggers: each trigger still creates its own run. To collapse a burst of
+  triggers into one run, use [`debounce`](#debounce). See [runs.list() best
+  practices](/runs/list-best-practices#using-a-fixed-delay-to-space-out-triggers).
+</Tip>
+
 ### `ttl`
 
 You can set a TTL (time to live) when triggering a task, which will automatically expire the run if it hasn't started within the specified time. This is useful for ensuring that a run doesn't get stuck in the queue for too long.
@@ -814,6 +820,8 @@ export const myTask = task({
 });
 ```
 
+Build the key from the work being done, like an order or event ID. A random value on every trigger never matches, so it never dedupes. See [runs.list() best practices](/runs/list-best-practices#using-a-random-idempotency-key).
+
 For more information, see our [Idempotency](/idempotency) documentation.
 
 ### `idempotencyKeyTTL`

package/docs/troubleshooting-alerts.mdx

@@ -243,13 +243,17 @@ This webhook is sent when a run fails. The payload is available on the `object`
 </ParamField>
 
 <ParamField path="object.environment.type" type="string">
-  Environment type (STAGING or PRODUCTION)
+  Environment type (`PRODUCTION`, `STAGING`, or `PREVIEW`)
 </ParamField>
 
 <ParamField path="object.environment.slug" type="string">
   Environment slug
 </ParamField>
 
+<ParamField path="object.environment.branchName" type="string">
+  Environment branch name (optional)
+</ParamField>
+
 <ParamField path="object.organization.id" type="string">
   Organization ID
 </ParamField>
@@ -311,7 +315,7 @@ This webhook is sent when a deployment succeeds. The payload is available on the
 </ParamField>
 
 <ParamField path="object.environment.type" type="string">
-  Environment type (STAGING or PRODUCTION)
+  Environment type (`PRODUCTION`, `STAGING`, or `PREVIEW`)
 </ParamField>
 
 <ParamField path="object.environment.slug" type="string">
@@ -346,6 +350,54 @@ This webhook is sent when a deployment succeeds. The payload is available on the
   Project name
 </ParamField>
 
+<ParamField path="object.git" type="object">
+  Git metadata for the deployment (optional). When present, `branch`, `commitSha`, `commitMessage`, `commitUrl` and `branchUrl` are always set.
+</ParamField>
+
+<ParamField path="object.git.branch" type="string">
+  Git branch
+</ParamField>
+
+<ParamField path="object.git.commitSha" type="string">
+  Short commit SHA (first 7 characters)
+</ParamField>
+
+<ParamField path="object.git.commitMessage" type="string">
+  Commit message (empty string if unavailable)
+</ParamField>
+
+<ParamField path="object.git.commitUrl" type="string">
+  URL of the commit
+</ParamField>
+
+<ParamField path="object.git.branchUrl" type="string">
+  URL of the branch
+</ParamField>
+
+<ParamField path="object.git.pullRequestNumber" type="number">
+  Pull request number (optional)
+</ParamField>
+
+<ParamField path="object.git.pullRequestTitle" type="string">
+  Pull request title (optional)
+</ParamField>
+
+<ParamField path="object.git.pullRequestUrl" type="string">
+  Pull request URL (optional)
+</ParamField>
+
+<ParamField path="object.git.provider" type="string">
+  Git provider (optional)
+</ParamField>
+
+<ParamField path="object.vercel" type="object">
+  Vercel metadata for the deployment (optional)
+</ParamField>
+
+<ParamField path="object.vercel.deploymentUrl" type="string">
+  URL of the deployment in the Vercel dashboard
+</ParamField>
+
 ### Deployment Failed Alert
 
 This webhook is sent when a deployment fails. The payload is available on the `object` property:
@@ -391,7 +443,7 @@ This webhook is sent when a deployment fails. The payload is available on the `o
 </ParamField>
 
 <ParamField path="object.environment.type" type="string">
-  Environment type (STAGING or PRODUCTION)
+  Environment type (`PRODUCTION`, `STAGING`, or `PREVIEW`)
 </ParamField>
 
 <ParamField path="object.environment.slug" type="string">
@@ -426,6 +478,53 @@ This webhook is sent when a deployment fails. The payload is available on the `o
   Project name
 </ParamField>
 
+<ParamField path="object.git" type="object">
+  Git metadata for the deployment (optional). When present, `branch`, `commitSha`, `commitMessage`, `commitUrl` and `branchUrl` are always set.
+</ParamField>
+
+<ParamField path="object.git.branch" type="string">
+  Git branch
+</ParamField>
+
+<ParamField path="object.git.commitSha" type="string">
+  Short commit SHA (first 7 characters)
+</ParamField>
+
+<ParamField path="object.git.commitMessage" type="string">
+  Commit message (empty string if unavailable)
+</ParamField>
+
+<ParamField path="object.git.commitUrl" type="string">
+  URL of the commit
+</ParamField>
+
+<ParamField path="object.git.branchUrl" type="string">
+  URL of the branch
+</ParamField>
+
+<ParamField path="object.git.pullRequestNumber" type="number">
+  Pull request number (optional)
+</ParamField>
+
+<ParamField path="object.git.pullRequestTitle" type="string">
+  Pull request title (optional)
+</ParamField>
+
+<ParamField path="object.git.pullRequestUrl" type="string">
+  Pull request URL (optional)
+</ParamField>
+
+<ParamField path="object.git.provider" type="string">
+  Git provider (optional)
+</ParamField>
+
+<ParamField path="object.vercel" type="object">
+  Vercel metadata for the deployment (optional)
+</ParamField>
+
+<ParamField path="object.vercel.deploymentUrl" type="string">
+  URL of the deployment in the Vercel dashboard
+</ParamField>
 
 ### Error Group Alert
 

package/docs/troubleshooting.mdx

@@ -251,7 +251,7 @@ If runs are staying in the `QUEUED` state for extended periods, check your concu
 **Solutions:**
 
 - **Increase concurrency limits** - If you're on a paid plan, increase your environment concurrency limit via the dashboard
-- **Review queue concurrency limits** - Check if individual queues have restrictive `concurrencyLimit` settings
+- **Review concurrency settings** - Check if your tasks have restrictive `concurrency` settings, or your queues a restrictive legacy `concurrencyLimit`. See [Concurrency](/concurrency)
 - **Check for stuck runs** - See if stalled runs are blocking new executions
 
 ### Runs queued because a billing limit was reached

package/docs/upgrading-packages.mdx

@@ -39,12 +39,12 @@ You can deploy using [GitHub Actions](/github-actions). We recommend that you lo
 
 <Steps>
   <Step title="Find your workflow file">
-    In your `.githubs/workflows` folder you can find your workflow yml files. You may have a prod
+    In your `.github/workflows` folder you can find your workflow yml files. You may have a prod
     and staging one.
   </Step>
   <Step title="Update the version for the run command">
     In the steps you'll see a `run` command. It will run the trigger.dev deploy CLI command. Make
-    sure to update this version to the latest version (e.g. `npx trigger.dev@3.0.0 deploy`).
+    sure to update this version to the latest version (e.g. `npx trigger.dev@4.7.3 deploy`).
   </Step>
 </Steps>
 
@@ -57,7 +57,7 @@ For example:
 ```json
 {
   "devDependencies": {
-    "trigger.dev": "3.0.0"
+    "trigger.dev": "4.7.3"
   }
 }
 ```

package/docs/vercel-integration.mdx

@@ -129,7 +129,17 @@ The integration sets this up for you:
 - It passes your commit SHA as the deployment's external id.
 - `VERCEL_GIT_COMMIT_SHA` is available at runtime on Vercel, so the SDK finds the matching id with no work from you.
 
-There is nothing to enable, and it works in production, staging and preview alike. Nothing is gated: your Vercel deployment is never held back.
+There is nothing to enable, and it works in production, staging and preview alike.
+
+### Production waits for your tasks
+
+A production deployment from a push to the branch Trigger.dev builds for production gets a blocking **Trigger.dev Build** check. Vercel holds the deployment until the task build for the same commit finishes, then assigns your production domains as usual. If the task build fails or is canceled, the check fails and the Vercel deployment doesn't go live, so your app never ships against tasks that didn't build.
+
+If no task build for the commit has started within 10 minutes, the check fails too.
+
+To retry after a failed build, re-run the **Trigger.dev deployment** check on the commit in GitHub. Once that build succeeds, redeploy from Vercel or push a new commit.
+
+A production deployment with no task build to wait for is never held: its check is marked skipped. That covers deployments from the Vercel CLI, from a branch that isn't your production branch in Trigger.dev, and from projects without a connected GitHub repository. Preview and staging deployments aren't held either: their check passes straight away, and version skew protection makes their runs wait for the matching task build instead.
 
 <Note>
   Version skew protection requires the `@trigger.dev/sdk` release that introduces external
@@ -146,8 +156,8 @@ To opt out, set `TRIGGER_AUTOMATIC_SKEW_VERSION_PROTECTION` to `0` on your Verce
 <Warning>
   **Automatic atomic deployments are deprecated.** Use [version skew
   protection](/deployment/atomic-deployment) instead — it needs no second Vercel deployment,
-  never gates your app's deploy, doesn't touch `Auto-assign Custom Production Domains`, and covers
-  staging and preview as well as production.
+  doesn't touch `Auto-assign Custom Production Domains`, and covers staging and preview as well as
+  production. Production deployments still wait for your task build through the blocking check.
 
   Nothing is being switched off. The setting stays in your project's Vercel settings, keeps working,
   and remains the way to hold your Vercel deployment back until your tasks have built. New

package/docs/versioning.mdx

@@ -51,7 +51,7 @@ Because your application and your tasks deploy separately, a release of your app
 
 ## Retries and reattempts
 
-When a task has an uncaught error it will [retry](/errors-retrying), assuming you have not set `maxAttempts` to 0. Retries are locked to the original version of the run.
+When a task has an uncaught error it will [retry](/errors-retrying), if the task has retries configured (the `retry` option or `retries.default` in your config). Retries are locked to the original version of the run.
 
 ## Replays
 

package/docs/wait-for-token.mdx

@@ -135,7 +135,7 @@ Create a waitpoint token.
 The `createToken` function accepts an object with the following properties:
 
 <ParamField query="timeout" type="string" optional>
-  The maximum amount of time to wait for the token to be completed. Defaults to "10m".
+  The maximum amount of time to wait for the token to be completed. If omitted, the token has no timeout. Accepts a duration string like `"30s"` or `"4w"`, or a `Date`.
 </ParamField>
 
 <ParamField query="idempotencyKey" type="string" optional>
@@ -144,7 +144,7 @@ The `createToken` function accepts an object with the following properties:
 </ParamField>
 
 <ParamField query="idempotencyKeyTTL" type="string" optional>
-  The time to live for the idempotency key. Defaults to "1h".
+  The time to live for the idempotency key. If omitted, the key does not expire.
 </ParamField>
 
 <ParamField query="tags" type="string[]" optional>
@@ -380,7 +380,7 @@ The `listTokens` function accepts an object with the following properties:
 </ParamField>
 
 <ParamField query="period" type="string" optional>
-  The period to filter by. Can be one of: `1h`, `1d`, `7d`, `30d`.
+  The period to filter by, as a duration string such as `1h`, `1d`, `7d` or `30d`.
 </ParamField>
 
 <ParamField query="from" type="Date | number" optional>

package/docs/webhooks/channels.mdx

@@ -0,0 +1,128 @@
+---
+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 { 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! })],
+  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 }; // an existing ref means edit-in-place on the next turn
+  },
+});
+```
+
+`send` is called to post the reply. `ctx.previousRef` is the ref you returned last time, so streaming or a follow-up edits the same message instead of posting a new one. 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.
+
+## 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. 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,80 @@
+---
+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. |
+| `set_webhook_secret` | Stores a secret the provider issued. |
+
+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.
+
+<Warning>
+  Trigger.dev stores credentials encrypted and doesn't display saved values. Copy a generated secret
+  before closing the dialog. Deliveries signed with the old secret fail verification after rotation.
+</Warning>