@trigger.dev/sdk 4.8.0 → 4.8.2

package/docs/introduction.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Trigger.dev docs"
 sidebarTitle: "Introduction"
-description: "Build and run durable AI agents and workflows in TypeScript. Long-running tasks with retries, queues, observability, and elastic scaling. Open source and self-hostable."
+description: "Build and run durable AI agents and workflows in TypeScript. Long-running tasks with retries, queues, webhooks, observability, and elastic scaling. Open source and self-hostable."
 mode: "center"
 ---
 
@@ -11,8 +11,8 @@ import AgentSetupPrompt from "/snippets/agent-setup-prompt.mdx";
   <Card title="Quick start" icon="rocket" href="/quick-start" color="#A8FF53">
     Go from zero to your first task in 3 minutes.
   </Card>
-  <Card title="Build AI agents" icon="robot" href="/guides/ai-agents/overview" color="#a855f7">
-    Agent patterns, worked examples, and the tools to run them in production.
+  <Card title="Build AI agents" icon="robot" href="/ai-chat/overview" color="#a855f7">
+    Durable, multi-turn agents with `chat.agent`, from your frontend to Slack and Linear.
   </Card>
   <Card title="AI coding assistants" icon="wand-magic-sparkles" href="/building-with-ai" color="#3B82F6">
     Let Claude Code, Cursor and Windsurf write correct Trigger.dev code with the MCP server, Skills and rules.
@@ -28,48 +28,124 @@ import AgentSetupPrompt from "/snippets/agent-setup-prompt.mdx";
 
 ## What is Trigger.dev?
 
-Trigger.dev is the open source platform for building and running durable AI agents and workflows in TypeScript. Run them for hours, configure automatic retries, control concurrency, and manage queues. There's no execution timeout, and no queue or worker infrastructure for you to build.
+Trigger.dev is the open source platform for building and running durable AI agents and workflows in TypeScript. You write tasks and agents in your existing codebase, and they run on Trigger.dev with retries, queues, waits, full tracing, and elastic scaling. There's no execution timeout, and no queue or worker infrastructure for you to build.
 
-You write agents and tasks in your existing codebase using our CLI and SDK, and get durable execution, queues, waits, full tracing, and elastic scaling without building any of it yourself.
+Trigger.dev's core is Apache-2.0 licensed. [Self-host it](/self-hosting/overview) on your own infrastructure, or let [Trigger.dev Cloud](https://cloud.trigger.dev) run it for you.
 
-Trigger.dev's core is Apache-2.0 licensed, a genuine OSI license. [Self-host it](/self-hosting/overview) on your own infrastructure, or let [Trigger.dev Cloud](https://cloud.trigger.dev) run it for you.
+## Build agents with `chat.agent`
 
-## Core concepts
+A `chat.agent` runs each conversation as one durable task. It wakes when a message arrives and idles between turns, and its state survives page refreshes, deploys, and crashes. Turn lifecycle, resuming a stream mid-reply, and approvals are handled for you, and your frontend connects with the AI SDK's `useChat`, with no API routes to write.
+
+```ts trigger/chat.ts
+import { chat } from "@trigger.dev/sdk/ai";
+import { anthropic } from "@ai-sdk/anthropic";
+
+export const supportAgent = chat.agent({
+  id: "support-agent",
+  run: async ({ messages, signal, streamText }) =>
+    streamText({
+      model: anthropic("claude-sonnet-4-5"),
+      messages,
+      abortSignal: signal,
+    }),
+});
+```
+
+<CardGroup cols={3}>
+  <Card title="Agent quick start" icon="rocket" href="/ai-chat/quick-start">
+    Build a chat agent and its frontend end to end.
+  </Card>
+  <Card title="Sessions" icon="layer-group" href="/ai-chat/sessions">
+    Each conversation's durable state and two-way stream, across all its runs.
+  </Card>
+  <Card title="Tools" icon="screwdriver-wrench" href="/ai-chat/tools">
+    Declare tools on your agent and get them back typed in `run()`.
+  </Card>
+  <Card title="Human in the loop" icon="hand" href="/ai-chat/patterns/human-in-the-loop">
+    Pause a tool call for approval and resume when a person decides.
+  </Card>
+  <Card title="Slack agents" icon="slack" href="/webhooks/slack">
+    Turn an agent into a native Slack agent with `@trigger.dev/slack`.
+  </Card>
+  <Card title="Linear agents" icon="list-check" href="/webhooks/linear">
+    Assign Linear issues to an agent with `@trigger.dev/linear`.
+  </Card>
+</CardGroup>
+
+Version your [prompts](/ai/prompts) in code and change them from the dashboard, and see every model step and tool call, with tokens, cost and latency, in [AI observability](/ai/observability).
+
+## Run work
 
 <CardGroup cols={2}>
   <Card title="Writing tasks" icon="pen-to-square" href="/tasks/overview" color="#A8FF53">
-    The durable functions at the core of Trigger.dev. Write them in your existing codebase, with retries and no timeouts.
+    The durable functions at the core of Trigger.dev, written in your existing codebase.
   </Card>
   <Card title="Triggering tasks" icon="bullseye-pointer" href="/triggering" color="#3b82f6">
-    Trigger a task from your backend, your frontend, a schedule, or another task.
+    Trigger a task from your backend, your frontend, or another task.
   </Card>
   <Card title="Runs" icon="play" href="/runs" color="#28bf5c">
-    Every execution of a task is a run, with its status, retries, and logs recorded.
+    Every execution of a task is a run, with its status, retries, logs and trace.
+  </Card>
+  <Card title="Realtime" icon="bolt" href="/realtime/overview" color="#F43F5E">
+    Stream run status and LLM output to your frontend with React hooks.
+  </Card>
+</CardGroup>
+
+## React to events
+
+<CardGroup cols={2}>
+  <Card title="Webhooks" icon="webhook" href="/webhooks/overview" color="#a855f7">
+    Hosted, verified endpoints for Stripe, GitHub and more, delivered to your tasks and agents.
+  </Card>
+  <Card title="Scheduled tasks" icon="clock" href="/tasks/scheduled" color="#f6cd46">
+    Run a task on a cron schedule, with timezone support.
+  </Card>
+  <Card title="Webhook waiters" icon="bell" href="/webhooks/waiters" color="#3b82f6">
+    Pause a run until a matching webhook arrives, like a payment confirmation.
   </Card>
-  <Card title="Idempotency" icon="fingerprint" href="/idempotency" color="#F43F5E">
-    Use an idempotency key so a retried or duplicated trigger runs once, not twice.
+  <Card title="Waits" icon="hourglass" href="/wait" color="#28bf5c">
+    Pause a run for a duration, until a date, or until a token is completed. A waiting run doesn't use compute.
   </Card>
 </CardGroup>
 
-## Build with agents
+## Run in production
 
-Build durable, multi-turn agents with the [chat agent](/ai-chat/overview): one long-running task per conversation, with the tools it can call, streaming, and resumability handled for you. Add human-in-the-loop approval by pausing a run on a [waitpoint](/wait-for-token) until a person signs off, and a waiting run doesn't consume compute. Stream run status and LLM output straight to your frontend with the [Realtime API](/realtime/overview) and React hooks, and record your Vercel AI SDK calls as spans with the model, token counts, cost and latency using [AI observability](/ai/observability). Version your [prompts](/ai/prompts) in code, then edit the text or swap the model from the dashboard without redeploying.
+<CardGroup cols={2}>
+  <Card title="Queues & concurrency" icon="layer-group" href="/queues" color="#3b82f6">
+    Control how many runs execute at once, globally or per tenant.
+  </Card>
+  <Card title="Machines" icon="microchip" href="/machines" color="#a855f7">
+    Choose the CPU and memory each task runs on.
+  </Card>
+  <Card title="Deployment" icon="cloud-arrow-up" href="/deployment/overview" color="#28bf5c">
+    Atomic, versioned deploys, with preview branches and environments.
+  </Card>
+  <Card title="Errors & retries" icon="arrows-rotate" href="/errors-retrying" color="#F43F5E">
+    Retry failed attempts automatically, and decide what happens when a task throws.
+  </Card>
+  <Card title="Logs, traces & metrics" icon="chart-line" href="/logging" color="#f6cd46">
+    A full trace of every run, with your logs and spans.
+  </Card>
+  <Card title="Query & dashboards" icon="table" href="/observability/query" color="#A8FF53">
+    Query your runs with TRQL, and build dashboards from the results.
+  </Card>
+</CardGroup>
 
-## Scale and scheduling
+## Frequently asked questions
 
-Set how many runs of a task execute at once, globally or per tenant, with [concurrency](/concurrency) and [queues](/queues). Run a task on a [cron schedule](/tasks/scheduled) with timezone support, choose the CPU and memory each task runs on with [machines](/machines), and control what happens when a task throws with [errors and retries](/errors-retrying).
+**Can I use Trigger.dev for background jobs, not just AI?** Yes. The same durable tasks, queues, retries, and [cron schedules](/tasks/scheduled) run any background job or workflow, with or without AI.
 
-## Self-hosting
+**How long can a run take?** As long as it needs. Runs have no maximum duration by default, and you can set a [`maxDuration`](/runs/max-duration) for a project, a task, or a single run to cap it.
 
-Trigger.dev is open source and you can self-host. Read the [overview guide](/self-hosting/overview), or how to do it with [Docker](/self-hosting/docker) or [Kubernetes](/self-hosting/kubernetes).
+**Do my serverless function timeouts apply?** No. Tasks run on Trigger.dev, not inside your serverless functions, so your platform's function timeout isn't in the execution path. Your backend triggers the task and returns.
 
-## Frequently asked questions
+**Can I receive webhooks without running a server?** Yes. Declare a [webhook endpoint](/webhooks/overview) in your code, and Trigger.dev hosts its URL, verifies each request, and delivers the event to your tasks and agents.
 
-**How do I add human-in-the-loop approval to an agent?** Pause the run on a [waitpoint](/wait-for-token) until a person approves the action. A waiting run doesn't consume compute, so it can wait minutes or days.
+**How do I add human-in-the-loop approval?** Pause the run on a [waitpoint](/wait-for-token) until a person approves, or use a [chat agent's approvals](/ai-chat/patterns/human-in-the-loop) for tool calls. A waiting run doesn't use compute, so it can wait minutes or days.
 
 **Does Trigger.dev support tool calling and MCP?** Yes. Agents call the tools you define, and the [MCP server](/building-with-ai) lets AI coding assistants trigger tasks, deploy, and read run traces.
 
-**Can I use Trigger.dev for background jobs, not just AI?** Yes. The same durable tasks, queues, retries, and [cron schedules](/tasks/scheduled) run any background job or workflow, with or without AI.
+**Can I self-host?** Yes. Trigger.dev is open source. Read the [self-hosting overview](/self-hosting/overview), or set it up with [Docker](/self-hosting/docker) or [Kubernetes](/self-hosting/kubernetes).
 
 ## Getting help
 
@@ -85,7 +161,7 @@ We'd love to hear from you or give you a hand getting started. Here are some way
     Our Discord is the best place to get help with any questions about Trigger.dev.
   </Card>
   <Card
-    title="Follow us on X (Twitter)"
+    title="Follow us on X"
     icon={
       <svg xmlns="http://www.w3.org/2000/svg" height="20" viewBox="0 0 512 512">
         <path d="M389.2 48h70.6L305.6 224.2 487 464H345L233.7 318.6 106.5 464H35.8L200.7 275.5 26.8 48H172.4L272.9 180.9 389.2 48zM364.4 421.8h39.1L151.1 88h-42L364.4 421.8z" />
@@ -112,7 +188,7 @@ We'd love to hear from you or give you a hand getting started. Here are some way
     href="https://github.com/triggerdotdev/trigger.dev"
     color="#fbbf24"
   >
-    Check us out our GitHub repo and give us a star if you like what we're doing.
+    Check out our GitHub repo, and give us a star if you like what we're doing.
   </Card>
 </CardGroup>
 
@@ -122,12 +198,16 @@ We'd love to hear from you or give you a hand getting started. Here are some way
 
 **Current major version:** v4 (`@trigger.dev/sdk` 4.x). Documentation under `/docs/v2` and `/docs/v3` describes superseded versions and should not be used.
 
-**Execution model:** tasks run on Trigger.dev infrastructure, not inside your serverless functions, so a platform function timeout is not in the execution path. A task runs until it finishes; you can cap runtime with `maxDuration` (minimum 5 seconds).
+**Execution model:** tasks run on Trigger.dev infrastructure, not inside your serverless functions, so a platform function timeout is not in the execution path. Runs have no maximum duration by default; `maxDuration` caps a run's compute time for a project, a task, or a single run, and `timeout.None` removes the cap.
 
 **Deploys:** each deploy is an atomic version. A run already in progress is not affected by code shipped after it started.
 
 **Durability and retries:** retries are automatic and configurable. A failed attempt is retried according to the task's retry settings; once retries are exhausted the run ends terminally as `FAILED`, and some crashes (for example out of memory) end the run as `CRASHED` without a retry. Idempotency keys deduplicate the task triggers and waits you key, so the same key runs once instead of again.
 
+**Agents:** `chat.agent` is imported from `@trigger.dev/sdk/ai`, not from `@trigger.dev/sdk`. Inside `run()`, call the `streamText` passed in the run options. It records each model step and tool call as a span by default. Slack and Linear agents use the `@trigger.dev/slack` and `@trigger.dev/linear` packages, and `slack()` requires a `startOn` filter (`appMentions()` answers @mentions).
+
+**Webhooks:** `webhooks.endpoint.define()` declares a hosted, verified endpoint that syncs on `trigger dev` and on deploy; `webhook()` subscribes a task with a filter, and `webhooks.waiter` pauses a run until a matching event arrives. Both come from `@trigger.dev/sdk`.
+
 **License:** the platform core is Apache-2.0 and the `@trigger.dev/sdk` package is MIT, permissive open source, not fair-code or source-available. Some features are gated, but the open source core is not relicensed or held back.
 
 **LLM observability coverage:** only Vercel AI SDK calls (`generateText`, `streamText`, `generateObject`) are recorded as spans. Raw `fetch` calls and provider SDKs used directly are not captured.

package/docs/limits.mdx

@@ -178,6 +178,47 @@ All of an environment's endpoints also share a per-environment limit, counted in
 | Pro          | 3,000 every 10 sec     |
 | Enterprise   | Set per organization   |
 
+## Webhook waiters
+
+A [waiter](/webhooks/waiters) is a run paused until a matching webhook arrives. The per-endpoint limit is also the most waiting runs one delivery can resume.
+
+| Pricing tier | Live waiters per environment | Live waiters per endpoint |
+| :----------- | :--------------------------- | :------------------------ |
+| Free         | 500                          | 100                       |
+| Hobby        | 2,000                        | 1,000                     |
+| Pro          | 25,000                       | 10,000                    |
+| Enterprise   | Set per organization         | Set per organization      |
+
+A waiter can wait for up to 90 days.
+
+## Webhook processing concurrency
+
+This limit controls how many webhook deliveries and waiter resumes are processed at once per environment. Additional deliveries wait their turn. It is not a limit on the runs those deliveries start, which use your normal [concurrency limits](#concurrency-limits).
+
+| Pricing tier | Limit                    |
+| :----------- | :----------------------- |
+| Free         | 5 concurrent deliveries  |
+| Hobby        | 10 concurrent deliveries |
+| Pro          | 50 concurrent deliveries |
+| Enterprise   | Set per organization     |
+
+## Webhook delivery retention
+
+How long [deliveries](/webhooks/deliveries) stay visible in the dashboard and the API.
+
+| Pricing tier | Limit                        |
+| :----------- | :--------------------------- |
+| Free         | 3 days                       |
+| Hobby        | 7 days                       |
+| Pro          | 30 days                      |
+| Enterprise   | 90, 180 or 365 days          |
+
+By default, deliveries are stored for at least 30 days, so upgrading your plan shows older deliveries that are still stored. An organization can ask us to store deliveries only for its retention period instead. Deliveries past that period are then deleted and can't be shown again after an upgrade.
+
+## Webhook subscribers
+
+An endpoint can have up to 25 subscribers (tasks, agent sessions and channels) on every plan.
+
 ## Log retention
 
 | Pricing tier | Limit   |

package/docs/mcp-tools.mdx

@@ -411,6 +411,10 @@ Generate a new signing secret for an endpoint and return it once, for providers
 
 **Parameters:**
 - `endpointId` (required): the endpoint's declared id (such as `payments`) or `wh_` id
+- `previousSecretTtlSeconds` (optional): keep accepting the replaced secret for this many seconds (up to 604800, 7 days) while the provider switches to the new one. Omit it, or pass `0`, to replace the secret immediately, for example when it leaked. The response says when the old secret stops working.
+
+**Example usage:**
+- `"Rotate the GitHub endpoint's secret and keep the old one working for a day"`
 
 ### set_webhook_secret
 
@@ -419,6 +423,7 @@ Store a signing secret or public key the provider issued, such as Stripe's `whse
 **Parameters:**
 - `endpointId` (required): the endpoint's declared id (such as `payments`) or `wh_` id
 - `secret` (required): the secret or public key
+- `previousSecretTtlSeconds` (optional): keep accepting the replaced secret for this many seconds (up to 604800, 7 days) while the provider switches to the new one. Omit it, or pass `0`, to replace the secret immediately, for example when it leaked. The response says when the old secret stops working.
 
 <Callout type="warning">
   `replay_webhook_delivery`, `generate_webhook_secret` and `set_webhook_secret` are write operations and are not available in readonly mode.

package/docs/observability/query.mdx

@@ -57,6 +57,35 @@ ORDER BY minute
 LIMIT 1000
 ```
 
+#### Platform limit metrics
+
+The `metrics` table also records how close your environment is to platform limits. These are the metrics behind [Limits alerts](/troubleshooting-alerts#limits-alerts):
+
+| Metric                          | What it shows                                    |
+| ------------------------------- | ------------------------------------------------ |
+| `queue.size.queued`             | Runs currently queued in the environment         |
+| `queue.size.limit`              | The environment's maximum queued runs            |
+| `webhook.processing.in_flight`  | Webhooks being processed now                     |
+| `webhook.processing.limit`      | The webhook processing concurrency limit         |
+| `webhook.ingress.denied`        | Incoming webhooks rejected by a rate limit       |
+| `webhook.ingress.remaining_min` | The lowest remaining rate limit allowance seen   |
+| `webhook.ingress.limit.tokens`  | The rate limit's allowance per window            |
+| `webhook.waiters.live`          | Runs currently waiting for a webhook             |
+| `webhook.waiters.limit.env`     | The environment's maximum webhook waiters        |
+| `webhook.waiters.refused`       | New webhook waiters that were refused            |
+
+```sql
+SELECT
+  timeBucket(),
+  maxIf(metric_value, metric_name = 'queue.size.queued') AS queued,
+  maxIf(metric_value, metric_name = 'queue.size.limit') AS queue_limit
+FROM metrics
+WHERE metric_name LIKE 'queue.size.%'
+GROUP BY timeBucket
+ORDER BY timeBucket
+LIMIT 1000
+```
+
 ### `prettyFormat()`
 
 Use `prettyFormat()` to format metric values for display:

package/docs/self-hosting/docker.mdx

@@ -389,6 +389,68 @@ EVENT_REPOSITORY_DEFAULT_STORE=clickhouse_v2
 
 This only affects new runs; existing runs continue to read from wherever their events were originally stored.
 
+### Move from the legacy clickhouse store
+
+The legacy `clickhouse` store (the `task_events_v1` table) is retired. If you set `EVENT_REPOSITORY_DEFAULT_STORE=clickhouse`, your webapp now writes and reads `clickhouse_v2` instead and logs a warning at startup. Events recorded in `task_events_v1` stay there but no longer show in the dashboard until you copy them over.
+
+<Steps titleSize="h4">
+  <Step title="Switch to clickhouse_v2">
+    Switch the store in your `.env` and restart the webapp:
+
+    ```bash .env
+    EVENT_REPOSITORY_DEFAULT_STORE=clickhouse_v2
+    ```
+  </Step>
+  <Step title="List the days to copy">
+    List the days that hold legacy events. The bundled ClickHouse container already sets `CLICKHOUSE_USER` and `CLICKHOUSE_PASSWORD`, and `clickhouse-client` reads them, so no credentials are needed:
+
+    ```bash
+    docker compose exec clickhouse clickhouse-client -q \
+      "SELECT toDate(start_time) AS day, count() FROM trigger_dev.task_events_v1 GROUP BY day ORDER BY day"
+    ```
+  </Step>
+  <Step title="Save the copy query">
+    Save the copy query as `copy-task-events-v1.sql`. It copies one day and skips events already in `task_events_v2`, so it's safe to run again if it's interrupted:
+
+    ```sql copy-task-events-v1.sql
+    INSERT INTO trigger_dev.task_events_v2
+      (environment_id, organization_id, project_id, task_identifier, run_id, start_time,
+       trace_id, span_id, parent_span_id, message, kind, status, attributes_text,
+       metadata, duration, expires_at, inserted_at)
+    SELECT
+      environment_id, organization_id, project_id, task_identifier, run_id, start_time,
+      trace_id, span_id, parent_span_id, message, kind, status, attributes_text,
+      metadata, duration, expires_at, toDateTime64(start_time, 3)
+    FROM trigger_dev.task_events_v1
+    WHERE toDate(start_time) = {day:Date}
+      AND (trace_id, span_id, start_time, kind, status) NOT IN (
+        SELECT trace_id, span_id, start_time, kind, status
+        FROM trigger_dev.task_events_v2
+        WHERE inserted_at >= {day:Date} AND inserted_at < {day:Date} + INTERVAL 8 DAY
+          AND toDate(start_time) = {day:Date}
+      );
+    ```
+  </Step>
+  <Step title="Copy each day">
+    Run it once per day from step 2, oldest first:
+
+    ```bash
+    docker compose exec -T clickhouse clickhouse-client --param_day=2026-08-01 \
+      --multiquery < copy-task-events-v1.sql
+    ```
+  </Step>
+  <Step title="Check a copied run">
+    Open a run from one of the copied days and check its trace and logs show.
+  </Step>
+</Steps>
+
+Copying one day at a time keeps memory use bounded on large tables. A future release removes `task_events_v1`, so copy anything you want to keep before then.
+
+<Note>
+  `EVENT_REPOSITORY_V1_REROUTE_ENABLED=0` keeps the legacy store while you migrate. It's
+  temporary and will be removed in a future release.
+</Note>
+
 ## Realtime streams
 
 Realtime streams power AI-agent token streaming and run streams. They default to **v2**, backed by the bundled `s2` service — [s2-lite](https://s2.dev), the open-source, self-hostable S2 server. It stores stream data in a persistent volume and is preconfigured in the webapp compose file, so no setup is required.

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

@@ -33,6 +33,9 @@ mode: "wide"
 | `TRIGGER_DEQUEUE_INTERVAL_MS`               | No       | 250         | Dequeue interval (ms).                                      |
 | `TRIGGER_DEQUEUE_IDLE_INTERVAL_MS`          | No       | 1000 (1s)   | Dequeue idle interval (ms).                                 |
 | `TRIGGER_DEQUEUE_MAX_CONSUMER_COUNT`        | No       | 1           | Max dequeue consumer count.                                 |
+| `RELEASE_UNSTARTED_RUNS_ENABLED`            | No       | false       | Set to true to requeue a run straight away when its container or pod can't be created, rather than after the pending execution timeout. Limited by `RUN_RELEASES_PER_MINUTE`. |
+| `RELEASE_FAILED_POD_RUNS_ENABLED`           | No       | false       | Set to true to requeue a run straight away when its pod fails before the run starts, rather than after the pending execution timeout. Independent of `RELEASE_UNSTARTED_RUNS_ENABLED`; the two share `RUN_RELEASES_PER_MINUTE`. Needs `FAILED_POD_HANDLER_ENABLED`. |
+| `RUN_RELEASES_PER_MINUTE`                   | No       | 5           | Different runs released within a minute, by either release flag, past which every release waits for the timeout again until a slot frees, a run already released included. 0 withholds every release; blank means the default. |
 | **Docker settings**                         |          |             |                                                             |
 | `DOCKER_API_VERSION`                        | No       | v1.41       | Docker API version. You should probably not touch this.     |
 | `DOCKER_STRIP_IMAGE_DIGEST`                 | No       | true        | Strip image digest in Docker. Turning off can cause issues. |
@@ -52,6 +55,7 @@ mode: "wide"
 | `KUBERNETES_IMAGE_PULL_SECRETS`             | No       | —           | Image pull secrets (CSV).                                   |
 | `KUBERNETES_EPHEMERAL_STORAGE_SIZE_LIMIT`   | No       | 10Gi        | Ephemeral storage size limit. Applies to all runs.          |
 | `KUBERNETES_EPHEMERAL_STORAGE_SIZE_REQUEST` | No       | 2Gi         | Ephemeral storage size request. Applies to all runs.        |
+| `KUBERNETES_POD_RESERVED_SOURCE_PORTS`      | No       | —           | Ports runs never use as the source port of an outbound connection, so they can't clash with services on those ports. CSV of ports or ranges, e.g. `50080,50081` or `50080-50090`. Sets the pod's `net.ipv4.ip_local_reserved_ports` sysctl. |
 | **Metrics**                                 |          |             |                                                             |
 | `METRICS_ENABLED`                           | No       | true        | Enable metrics.                                             |
 | `METRICS_COLLECT_DEFAULTS`                  | No       | true        | Collect default metrics.                                    |

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

@@ -88,6 +88,11 @@ mode: "wide"
 | `API_RATE_LIMIT_METRICS_MAX_ENTRIES`             | No       | 10000                 | Cap on distinct (environment, bucket) entries held between flushes.                                                |
 | `API_RATE_LIMIT_METRICS_WAIT_FOR_ASYNC_INSERT`   | No       | 0                     | Wait for ClickHouse to write each async insert of API rate limit metrics, surfacing write failures.                |
 | `API_RATE_LIMIT_METRICS_INSERT_BUSY_TIMEOUT_MS`  | No       | 10000                 | How long ClickHouse buffers API rate limit metric inserts before writing a part.                                   |
+| `WEBHOOK_METRICS_FLUSH_INTERVAL_MS`              | No       | 10000                 | How often aggregated webhook limit metrics are flushed to ClickHouse.                                              |
+| `WEBHOOK_METRICS_MAX_ENTRIES`                    | No       | 10000                 | Cap on distinct (environment, bucket) entries held between flushes.                                                |
+| `WEBHOOK_METRICS_MAX_ENDPOINTS`                  | No       | 500                   | Cap on endpoints with their own webhook metric rows per environment and bucket; environment totals still count all. |
+| `QUEUE_SIZE_METRICS_INTERVAL_SEC`                | No       | 30                    | Queue size sampling interval in seconds; must divide 60.                                                           |
+| `QUEUE_SIZE_METRICS_MAX_ENVS`                    | No       | 2000                  | Most environments sampled per interval.                                                                            |
 | `DEPLOYMENT_RATE_LIMIT_REFILL_INTERVAL`          | No       | 10s                   | Deployment endpoints rate limit refill interval.                                                                   |
 | `DEPLOYMENT_RATE_LIMIT_MAX`                      | No       | 1500                  | Deployment endpoints rate limit max.                                                                               |
 | `DEPLOYMENT_RATE_LIMIT_REFILL_RATE`              | No       | 500                   | Deployment endpoints rate limit refill rate.                                                                       |
@@ -123,6 +128,14 @@ mode: "wide"
 | `ARTIFACTS_OBJECT_STORE_ACCESS_KEY_ID`           | No       | —                     | Optional artifacts store access key.                                                                               |
 | `ARTIFACTS_OBJECT_STORE_SECRET_ACCESS_KEY`       | No       | —                     | Optional artifacts store secret key.                                                                               |
 | `ARTIFACTS_OBJECT_STORE_REGION`                  | No       | —                     | Optional artifacts store region.                                                                                   |
+| `DEPLOYMENT_INDEX_OBJECT_STORE_BASE_URL`         | No       | —                     | Optional separate store for deployment index snapshots. If not set, uses main object store.                        |
+| `DEPLOYMENT_INDEX_OBJECT_STORE_BUCKET`           | No       | —                     | Deployment index store bucket. Required together with the base URL.                                                |
+| `DEPLOYMENT_INDEX_OBJECT_STORE_ACCESS_KEY_ID`    | No       | —                     | Deployment index store access key.                                                                                 |
+| `DEPLOYMENT_INDEX_OBJECT_STORE_SECRET_ACCESS_KEY` | No       | —                     | Deployment index store secret key.                                                                                 |
+| `DEPLOYMENT_INDEX_OBJECT_STORE_REGION`           | No       | —                     | Deployment index store region.                                                                                     |
+| `DEPLOYMENT_INDEX_OBJECT_STORE_SERVICE`          | No       | s3                    | Deployment index store service.                                                                                    |
+| `DEPLOYMENT_INDEX_UPLOAD_MAX_ATTEMPTS`           | No       | 4                     | Attempts to store a deployment's index before the deploy fails.                                                    |
+| `DEPLOYMENT_INDEX_CAPTURE_ENABLED`               | No       | false                 | Set to true to store each deployment's full index in object storage when it deploys. |
 | **Alerts**                                       |          |                       |                                                                                                                    |
 | `ORG_SLACK_INTEGRATION_CLIENT_ID`                | No       | —                     | Slack client ID. Required for Slack alerts.                                                                        |
 | `ORG_SLACK_INTEGRATION_CLIENT_SECRET`            | No       | —                     | Slack client secret. Required for Slack alerts.                                                                    |
@@ -160,6 +173,7 @@ mode: "wide"
 | `SERVER_OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT`  | No       | 8192                  | OTel span attribute value length limit.                                                                            |
 | **Task events**                                  |          |                       |                                                                                                                    |
 | `EVENT_REPOSITORY_DEFAULT_STORE`                 | No       | postgres              | Where to store task events. Set to `clickhouse_v2` to store in ClickHouse (recommended for production).            |
+| `EVENT_REPOSITORY_V1_REROUTE_ENABLED`            | No       | 1                     | Routes the retired `clickhouse` store to `clickhouse_v2`, for new events and for reads. Set `EVENT_REPOSITORY_DEFAULT_STORE=clickhouse_v2` and [copy older events](/self-hosting/docker#move-from-the-legacy-clickhouse-store) to keep them. `0` keeps the legacy store temporarily and will be removed. |
 | `EVENT_REPOSITORY_POSTGRES_WRITES_DISABLED`      | No       | 0                     | Skip all PostgreSQL task-event writes (set to `1`). Only enable when `EVENT_REPOSITORY_DEFAULT_STORE` is `clickhouse_v2`, otherwise task events are lost. |
 | **Realtime**                                     |          |                       |                                                                                                                    |
 | `REALTIME_BACKEND_NATIVE_ENABLED`                | No       | 0                     | Set to `1` to enable native realtime run subscriptions and change notifications. When `0`, subscriptions use Electric. The Helm chart sets this to `1`. |
@@ -192,6 +206,18 @@ mode: "wide"
 | `RUN_ENGINE_DEFAULT_MAX_TTL`                     | No       | —                     | Maximum TTL for all runs (e.g. "14d"). Runs without a TTL use this as default; runs with a larger TTL are clamped. |
 | `MAXIMUM_DEV_QUEUE_SIZE`                         | No       | —                     | Maximum queued runs per queue in development environments.                                                         |
 | `MAXIMUM_DEPLOYED_QUEUE_SIZE`                    | No       | —                     | Maximum queued runs per queue in deployed (staging/prod) environments.                                             |
+| **Webhooks**                                     |          |                       |                                                                                                                    |
+| `WEBHOOK_ENABLED`                                | No       | 0                     | Set to `1` to run hosted webhooks: ingest, delivery and waiters. See [Webhooks](#webhooks). |
+| `WEBHOOK_REDIS_HOST`                             | No       | localhost             | A node of the Redis cluster webhooks use for their queue and waiters. It must run in cluster mode. |
+| `WEBHOOK_REDIS_PORT`                             | No       | 6379                  | Port of that node. |
+| `WEBHOOK_REDIS_USERNAME`                         | No       | —                     | Webhooks Redis username. |
+| `WEBHOOK_REDIS_PASSWORD`                         | No       | —                     | Webhooks Redis password. |
+| `WEBHOOK_REDIS_TLS_DISABLED`                     | No       | `REDIS_TLS_DISABLED`  | Set to `true` to connect to the webhooks Redis without TLS. |
+| `WEBHOOK_INGRESS_ORIGIN`                         | No       | `API_ORIGIN`          | Public origin of the webhook URLs, for when you serve them from their own host. |
+| `WEBHOOK_INGRESS_BODY_SIZE_LIMIT_MB`             | No       | 1                     | Largest webhook request body accepted, in MB. |
+| `WEBHOOK_DATABASE_URL`                           | No       | `DATABASE_URL`        | A separate PostgreSQL database for webhook endpoints and deliveries. |
+| `WEBHOOK_DELIVERY_RETENTION_DAYS`                | No       | 30                    | How many days of deliveries the dashboard and API show. It doesn't delete anything: deliveries are kept for `WEBHOOK_DELIVERY_STORAGE_DAYS`, or longer when this is higher. |
+| `WEBHOOK_DELIVERY_STORAGE_DAYS`                  | No       | 30                    | How long deliveries are stored before they're deleted. Must be one of `3`, `7`, `30`, `90`, `180` or `365`; any other value stops the webapp from starting. |
 | **Misc**                                         |          |                       |                                                                                                                    |
 | `TRIGGER_TELEMETRY_DISABLED`                     | No       | —                     | Disable telemetry.                                                                                                 |
 | `NODE_MAX_OLD_SPACE_SIZE`                        | No       | 8192                  | Maximum memory allocation for Node.js heap in MiB (e.g. "4096" for 4GB).                                           |
@@ -202,6 +228,18 @@ mode: "wide"
 | `ADMIN_DASHBOARD_ENABLED`                        | No       | 1                     | Set to anything other than `1` or `true` to disable the admin dashboard and user impersonation on this instance.   |
 | `EVENT_LOOP_MONITOR_ENABLED`                     | No       | 1                     | Node.js event loop lag monitor.                                                                                    |
 
+## Webhooks
+
+Hosted webhooks are off on a self-hosted instance until you turn them on:
+
+1. Run a Redis (or Valkey) cluster for webhooks and point `WEBHOOK_REDIS_HOST` and `WEBHOOK_REDIS_PORT` at one of its nodes. The webhook engine connects in cluster mode, so a standalone Redis won't work.
+2. Set `WEBHOOK_ENABLED=1` on the webapp.
+3. Give organizations access with the `hasWebhooksAccess` feature flag: turn it on for everyone on the admin dashboard's **Global Feature Flags** page, or for one organization from its feature flags on the **Organizations** page. An organization without it doesn't see Webhooks in the dashboard, and its deploys don't sync endpoints.
+
+Webhook URLs are served from `WEBHOOK_INGRESS_ORIGIN`, which defaults to `API_ORIGIN`, so providers need to reach that origin from the internet.
+
+The Docker Compose setup only passes the variables listed under the webapp service's `environment` in `hosting/docker/webapp/docker-compose.yml`, so add the webhook variables there. With the Helm chart, set them in `webapp.extraEnvVars`.
+
 ## Multi-Provider Object Storage
 
 The object storage system supports multiple S3-compatible providers (R2, S3, GCS, MinIO, etc.) using protocol prefixes. This enables migrating between providers without breaking existing runs.

package/docs/self-hosting/kubernetes.mdx

@@ -679,6 +679,8 @@ webapp:
 
 This only affects new runs; existing runs continue to read from wherever their events were originally stored.
 
+If you set `EVENT_REPOSITORY_DEFAULT_STORE` to the legacy `clickhouse` store, switch it to `clickhouse_v2`. To keep events recorded before the switch, follow [Move from the legacy clickhouse store](/self-hosting/docker#move-from-the-legacy-clickhouse-store) and run the queries with `kubectl exec` against your ClickHouse pod.
+
 ### Realtime streams
 
 Realtime streams power AI-agent token streaming and run streams. They default to **v2**, backed by the bundled `s2` deployment — [s2-lite](https://s2.dev), the open-source, self-hostable S2 server. The chart deploys it with a persistent volume, so no extra services are required.

package/docs/self-hosting/overview.mdx

@@ -121,6 +121,8 @@ You own a custom base image. It must provide:
 
 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.
 
+A custom image is yours to harden. Deploys on the published images remove trust in publicly compromised certificate authorities and point Node.js and Python at the OS trust store. Stages built on a custom image get neither, and run with the certificate settings the image ships with. Keeping a custom image patched, trust store included, is your responsibility.
+
 <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.

package/docs/troubleshooting-alerts.mdx

@@ -3,6 +3,8 @@ title: "Alerts"
 description: "Get alerted when runs or deployments fail, or when deployments succeed."
 ---
 
+import { PrivateBeta } from "/snippets/feature-status.jsx";
+
 We support receiving alerts for the following events:
 - Run fails
 - Deployment fails
@@ -44,6 +46,43 @@ Click on the triple dot menu on the right side of the table row and select "Disa
 </Steps>
 
 
+## Limits alerts
+
+<PrivateBeta flag="alertsEnabled" />
+
+A **Limits** alert watches limits that can interrupt or degrade runtime flow. Pick one limit for a single alert, or several (or "Watch all limits") for one combined alert.
+
+| Group    | What you can watch                                                                                                                                                       |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Platform | API rate limit running out, Environment concurrency filling up, Queue size nearing its limit                                                                              |
+| Webhooks | Webhook processing saturating, Webhook ingress getting rate-limited, Webhook endpoint getting rate-limited, Webhook waiters running out                                  |
+
+### Signals
+
+Each limit has up to two signals. Choose one or both:
+
+- **Limit reached**: the limit is already affecting traffic, for example requests are being rejected.
+- **Approaching the limit**: usage has reached a share of the limit. The default is 80%, and you can change it.
+
+Queue size only has the approaching signal.
+
+### Any or all
+
+When you watch more than one limit, choose when the alert raises:
+
+- **Any**: raise when at least one selected limit is true.
+- **All**: raise only when every selected limit is true at the same time.
+
+### Queue metrics
+
+Environment concurrency and queue size need queue metrics for your environment. If they aren't available, they aren't offered when you create the alert.
+
+### No data
+
+A limit shows "No data" until its metrics exist, for example before your environment has made any API requests or received any webhooks. You can query these metrics yourself, see [Platform limit metrics](/observability/query#platform-limit-metrics).
+
+You can also create these alerts with the [API](/management/alerts/create).
+
 ## Error group alerts
 
 Error group alerts are **issue-based**, not run-based. They are created from the **Errors** page in the dashboard (the "Configure alerts…" button), not from the New alert modal on the Alerts page. Once created they show up in the Alerts table alongside your other alerts, labelled "Error group".

package/docs/webhooks/deliveries.mdx

@@ -70,6 +70,10 @@ The [MCP server](/mcp-introduction) has `list_webhook_deliveries` (filter by end
 | [`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. |
 
+## Retention
+
+Deliveries stay visible for 3 days on Free, 7 days on Hobby, 30 days on Pro, and 90, 180 or 365 days on Enterprise. See [Limits](/limits#webhook-delivery-retention).
+
 ## Deduplication
 
 Trigger.dev uses the endpoint and idempotency key to deduplicate incoming events. Delivery records and task runs have separate deduplication windows:

package/docs/webhooks/overview.mdx

@@ -83,6 +83,14 @@ The CLI finds your endpoints and subscribers during `trigger dev` and deployment
 
 A request must pass verification before anything else happens. Provider handshakes are answered directly and create no delivery. A verified request is checked for duplicates, recorded, and then routed: each subscriber's filter is checked, matching subscribers run, and waiting runs whose match fits the event are resumed. The delivery records a result per subscriber.
 
+## Pricing and limits
+
+Webhooks have no separate charge on Trigger.dev Cloud. Receiving, verifying, filtering and recording deliveries is included in every plan. The runs a delivery starts or resumes are billed like any other run: a per-run invocation cost plus compute time. See [pricing](https://trigger.dev/pricing).
+
+A delivery that no subscriber's filter matches starts no run for any subscriber, so it costs nothing. A run already waiting for that webhook still resumes. A run [waiting](/webhooks/waiters) for a webhook is suspended, so it uses no compute until the webhook arrives.
+
+Each plan sets limits on the ingest rate, waiting runs, processing concurrency and how long deliveries are kept. See [Limits](/limits#webhook-ingest-rate-limits).
+
 ## Connect it
 
 Every endpoint can produce a setup prompt for an AI coding agent. It holds the URL, the events your subscribers filter on, and the steps for registering the endpoint and its signing secret with the provider. Copy it from the endpoints list or the endpoint's page, or read it with the MCP server's `get_webhook_endpoint_details` tool. See [Connect a provider](/webhooks/connect).

package/docs/webhooks/sources.mdx

@@ -106,6 +106,8 @@ Supabase database webhooks aren't signed, so `supabase()` checks a shared secret
 
 Slack also ships as a chat channel in `@trigger.dev/slack`.
 
+For a complete project built on `resend()`, see the [Resend email agent example](https://github.com/triggerdotdev/examples/tree/main/resend-slack-email-agent). It drafts replies to a Resend inbox and waits for your approval in Slack before sending them.
+
 ### Hookdeck
 
 `hookdeck()` verifies requests that a [Hookdeck](https://hookdeck.com) connection forwards to the endpoint. Hookdeck forwards the original provider's body unchanged, so pass that provider's event type:
@@ -242,7 +244,7 @@ Custom sources support these schemes:
 | `hmac` | Computes an HMAC over the raw body or a signing template and compares it with a request header. |
 | `shared-secret` | Compares a static token supplied in a header, bearer token, basic authentication, or request body. |
 | `url-secret` | Compares a token in a URL query parameter. Hosted endpoints don't support path placement. |
-| `asymmetric` | Verifies an Ed25519, ECDSA, or RSA signature using the provider's public key. |
+| `asymmetric` | Verifies an Ed25519, ECDSA (P-256 with SHA-256, P-384 with SHA-384), or RSA-SHA256 signature using the provider's public key. Set `prehash: "sha256"` when the provider signs a SHA-256 digest of the signing string instead of the string itself. |
 
 <Warning>
   Query parameters can appear in access logs, proxies, and traces. Prefer a header-based scheme when

package/docs/webhooks/waiters.mdx

@@ -178,13 +178,13 @@ if (!result.cancelled) {
 
 | Limit | Default |
 | --- | --- |
-| Live waiters per endpoint | 10,000. This is also the most one delivery can resume. |
-| Live waiters per environment | 1,000,000 on self-hosted installs. |
+| Live waiters per endpoint | Depends on your plan on Trigger.dev Cloud, 10,000 on self-hosted installs. This is also the most one delivery can resume. |
+| Live waiters per environment | Depends on your plan on Trigger.dev Cloud, 1,000,000 on self-hosted installs. |
 | Distinct sets of `match` paths per endpoint | 25 |
 | Paths per `match` | 5 |
 | Tags per waiter | 10 |
 | Timeout | 24 hours by default, 90 days at most |
 
-On Trigger.dev Cloud the per-endpoint and per-environment limits depend on your plan. Self-hosted installs can change them with `WEBHOOK_WAITER_MAX_PER_ENDPOINT`, `WEBHOOK_WAITER_MAX_PER_ENVIRONMENT` and `WEBHOOK_WAITER_MAX_SHAPES`.
+On Trigger.dev Cloud the per-endpoint and per-environment limits depend on your plan: see [Limits](/limits#webhook-waiters). Self-hosted installs can change them with `WEBHOOK_WAITER_MAX_PER_ENDPOINT`, `WEBHOOK_WAITER_MAX_PER_ENVIRONMENT` and `WEBHOOK_WAITER_MAX_SHAPES`.
 
 A delivery that resumes waiters shows one **Waiting runs** row on its [delivery page](/webhooks/deliveries#where-a-delivery-went) with how many matched, resumed and failed. A delivery that arrives while runs are waiting but matches none of them, and no subscriber takes, is `UNMATCHED`.