diff --git a/.changeset/cost-skill-webhook-filters.md b/.changeset/cost-skill-webhook-filters.md new file mode 100644 index 00000000000..d58c457da50 --- /dev/null +++ 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 no subscriber's filter matches starts no run and costs no compute. diff --git a/docs/how-to-reduce-your-spend.mdx b/docs/how-to-reduce-your-spend.mdx index b19bdb8476b..1f629cf12c7 100644 --- 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 filter matches is recorded as `FILTERED` and starts no run, so you aren't charged compute for it. 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 index 77f31209b5f..d90ddb87691 100644 --- a/docs/limits.mdx +++ b/docs/limits.mdx @@ -178,6 +178,46 @@ 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. More 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 | + +## 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 | + +Deliveries are stored for at least 30 days, so upgrading your plan shows older deliveries right away. + +## 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 index 836c85524ed..99f01a14d26 100644 --- 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 and 30 days on Pro. 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 index 84d7f437470..7fb38fa323a 100644 --- 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, by compute time. See [pricing](https://trigger.dev/pricing). + +A delivery that no subscriber's filter matches starts no run, so it uses no compute. 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 index 1787e34cc90..7a7d276cb5a 100644 --- a/docs/webhooks/waiters.mdx +++ b/docs/webhooks/waiters.mdx @@ -185,6 +185,6 @@ if (!result.cancelled) { | 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 index 2485ae1ab5b..43a57402691 100644 --- 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 that no subscriber's filter matches starts no run and costs no compute. 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.