jackbridger · Oct 22, 2026 · Oct 26, 2026 · Oct 26, 2026
diff --git a/.changeset/cost-skill-webhook-filters.md b/.changeset/cost-skill-webhook-filters.md
@@ -0,0 +1,5 @@
+---
+"@trigger.dev/sdk": patch
+---
+
+The bundled `trigger-cost-savings` skill now notes that a webhook delivery starts no run when no subscriber's filter matches, so it costs no compute.
diff --git a/docs/how-to-reduce-your-spend.mdx b/docs/how-to-reduce-your-spend.mdx
@@ -190,6 +190,10 @@ export const waitpointTask = task({
 
 Waiting saves you compute, but it doesn't always free up concurrency — see [Wait](/wait).
 
+## Filter webhooks before they start runs
+
+Give each [webhook](/webhooks/overview) subscriber a [filter](/webhooks/filters) so it only runs for the events it handles. A delivery that no subscriber's filter matches starts no run for any subscriber, so you aren't charged for it. Filters only apply to subscribers: a run [waiting](/webhooks/waiters) for a matching webhook still resumes and uses compute. Receiving webhooks has no separate charge.
+
 ## Use debounce to consolidate multiple triggers
 
 When a task might be triggered multiple times in quick succession, use debounce to consolidate them into a single run. This is useful for document indexing, webhook aggregation, cache invalidation, and real-time sync scenarios.

diff --git a/docs/limits.mdx b/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   |

diff --git a/docs/webhooks/deliveries.mdx b/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:

diff --git a/docs/webhooks/overview.mdx b/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).

diff --git a/docs/webhooks/waiters.mdx b/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`.
diff --git a/packages/trigger-sdk/skills/trigger-cost-savings/SKILL.md b/packages/trigger-sdk/skills/trigger-cost-savings/SKILL.md
@@ -105,6 +105,7 @@ Larger machines cost proportionally more per second of compute:
 ## Key principles
 
 - **Waits > 5 seconds are free** — checkpointed, no compute charge.
+- **Webhook filters skip runs** — a webhook delivery starts no run when no subscriber's filter matches, so it costs no compute (a run already waiting for that webhook still resumes). Receiving webhooks has no separate charge.
 - **Start small, scale up** — the default `small-1x` is right for most tasks.
 - **I/O-bound tasks don't need big machines** — API calls and DB queries wait on the network.
 - **Debounce saves the most on high-frequency tasks** — it consolidates bursts into single runs.