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

package/docs/observability/dashboards.mdx

@@ -45,6 +45,68 @@ You can also filter the data by:
 4. For charts you write [TRQL queries](/observability/query) and choose a visualization type.
 5. You can resize and reposition widgets on your dashboards.
 
+## Managing dashboards with the SDK
+
+Custom dashboards can also be created and edited from code, so you can keep them in your repository and set them up from CI or a script. `query.dashboards` covers the same operations as the dashboard UI.
+
+```ts scripts/dashboards.ts
+import { query } from "@trigger.dev/sdk";
+
+const dashboard = await query.dashboards.create({
+  title: "Email tasks",
+  widgets: [
+    { title: "Overview", display: { type: "title" } },
+    {
+      title: "Total runs",
+      query: "SELECT count() AS total FROM runs WHERE task_identifier = 'send-email'",
+      display: { type: "bignumber", column: "total", aggregation: "sum" },
+    },
+    {
+      title: "Runs per day",
+      query:
+        "SELECT timeBucket(), count() AS runs FROM runs WHERE task_identifier = 'send-email' GROUP BY timeBucket ORDER BY timeBucket",
+      display: {
+        type: "chart",
+        chartType: "bar",
+        xAxisColumn: "timebucket",
+        yAxisColumns: ["runs"],
+        groupByColumn: null,
+        stacked: false,
+        sortByColumn: null,
+        sortDirection: "asc",
+        aggregation: "sum",
+      },
+    },
+  ],
+});
+
+console.log(dashboard.id); // dashboard_...
+```
+
+Widgets without a `position` are stacked full width in the order you list them. Pass `position: { x, y, w, h }` on a 12-column grid to place a widget yourself.
+
+To keep a dashboard in sync with code, replace all of its widgets in one call. Widgets you keep, matched by `id`, stay where they are unless you pass a new `position`:
+
+```ts scripts/dashboards.ts
+const current = await query.dashboards.retrieve(dashboard.id);
+
+await query.dashboards.replace(dashboard.id, {
+  widgets: [
+    {
+      id: "failures",
+      title: "Failed runs",
+      query: "SELECT count() AS failed FROM runs WHERE status = 'Failed'",
+      display: { type: "bignumber", column: "failed", aggregation: "sum" },
+    },
+  ],
+  revision: current.revision,
+});
+```
+
+`revision` is optional. When you pass the revision you last read, the write fails with a 409 if someone changed the dashboard in the meantime, instead of overwriting their change.
+
+Every widget query is checked against the queryable tables when you save it, so a typo in a table or column name fails the request with the list of valid columns. `query.dashboards.widgets.add`, `widgets.update` and `widgets.del` change one widget at a time. Creating a dashboard or widget past your plan's limits returns a 403. See the [Query API reference](/management/query/create-dashboard) for every endpoint.
+
 ## Performance considerations
 
 ### Optimize queries for metrics

package/docs/runs/max-duration.mdx

@@ -4,6 +4,10 @@ sidebarTitle: "Max duration"
 description: "Set a maximum duration for a task to run."
 ---
 
+Runs have no maximum duration. You set a default `maxDuration` for your project and can override it per task or per run, or set it to `timeout.None` to let a run execute indefinitely.
+
+Trigger is built for long running AI agents and workflows and we have seen Trigger.dev users with runs lasting more than six months.
+
 The `maxDuration` parameter sets a maximum compute time limit for tasks. When a task exceeds this duration, it will be automatically stopped. This helps prevent runaway tasks and manage compute resources effectively.
 
 You must set a default maxDuration in your `trigger.config.ts` file, which will apply to all tasks unless overridden:

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

@@ -65,6 +65,7 @@ mode: "wide"
 | `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).   |
+| `RUNNER_KILL_REPORTS_ENABLED`               | No       | true        | Fail a run straight away when its pod is killed, as out of memory only if Kubernetes reports `OOMKilled`. |
 | **Debug**                                   |          |             |                                                             |
 | `DEBUG`                                     | No       | false       | Enable debug logs.                                          |
 | `SEND_RUN_DEBUG_LOGS`                       | No       | false       | Send run debug logs to the platform.                        |

package/docs/webhooks/channels.mdx

@@ -4,6 +4,10 @@ description: "Point Slack (or any chat surface) at an agent: messages become tur
 sidebarTitle: "Channels"
 ---
 
+import WebhooksBetaBanner from "/snippets/webhooks-beta-banner.mdx";
+
+<WebhooksBetaBanner />
+
 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`:
@@ -59,12 +63,12 @@ const mySurface = chat.channels.custom({
   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
+    return { ref }; // later sends in the same turn get it back as ctx.previousRef
   },
 });
 ```
 
-`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).
+`send` is called to post the reply. Within a turn, `ctx.previousRef` is the ref you returned from the turn's earlier `send` (the acknowledgement, or the message being streamed), so later sends edit that message instead of posting a new one. Each turn starts without a ref: the next turn's answer is a new message. 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.
 

package/docs/webhooks/connect.mdx

@@ -4,6 +4,10 @@ description: "Register an endpoint's URL and signing secret with the provider, b
 sidebarTitle: "Connect a provider"
 ---
 
+import WebhooksBetaBanner from "/snippets/webhooks-beta-banner.mdx";
+
+<WebhooksBetaBanner />
+
 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.

package/docs/webhooks/deliveries.mdx

@@ -4,6 +4,10 @@ description: "Inspect webhook payloads, where each delivery went, and the runs i
 sidebarTitle: "Deliveries and endpoints"
 ---
 
+import WebhooksBetaBanner from "/snippets/webhooks-beta-banner.mdx";
+
+<WebhooksBetaBanner />
+
 **A delivery records a verified webhook event and what happened to it at each subscriber.** Find deliveries on an endpoint's **Deliveries** tab. A run that a delivery triggered links back to it, and to its endpoint, from the run's **Detail** tab.
 
 ## Endpoints

package/docs/webhooks/filters.mdx

@@ -4,6 +4,10 @@ description: "Choose which verified webhook events reach each subscriber, by pay
 sidebarTitle: "Filters"
 ---
 
+import WebhooksBetaBanner from "/snippets/webhooks-beta-banner.mdx";
+
+<WebhooksBetaBanner />
+
 **A filter selects which verified deliveries reach a subscriber.** Each subscriber on an [endpoint](/webhooks/overview) has its own filter, so one delivery can start one task and skip another. A delivery no subscriber takes is recorded with status `FILTERED`, so you can inspect it in the dashboard.
 
 ## Add a filter
@@ -27,7 +31,36 @@ export const largePayments = webhook({
 
 The same `filter` works on a [`chat.event`](/webhooks/session-routing#filtering), a channel connector, and a [waiter](/webhooks/waiters), where it is checked after the waiter's `match`.
 
-The filter is checked against the [endpoint's event type](/webhooks/sources#typing-the-event). Concrete types catch missing fields and incompatible literals. Fields typed as `unknown`, including values in Stripe's default `data.object`, allow arbitrary non-empty field paths. Operator literals and path structure are still checked.
+The filter is checked against the [endpoint's event type](/webhooks/sources#typing-the-event). Concrete types catch missing fields and incompatible literals. Fields typed as `unknown`, including values in Stripe's default `data.object`, allow arbitrary non-empty field paths. Operator literals and path structure are still checked. A filter built at runtime (typed as `string` rather than a string literal) skips the compile-time check, and is validated when the endpoint is deployed.
+
+## Narrow a union event
+
+When the endpoint's event is a union, such as `webhooks.stripe<Stripe.Event>()`, an `event.<field> == '<value>'` clause selects the members whose field can hold that value. The rest of that `&&` chain is checked against those members, and the handler's `event` has their type:
+
+```ts /trigger/checkouts.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+import type Stripe from "stripe";
+
+export const stripe = webhooks.endpoint.define({
+  id: "stripe",
+  source: webhooks.stripe<Stripe.Event>(),
+});
+
+export const checkouts = webhook({
+  id: "checkouts",
+  endpoint: stripe,
+  filter: "event.type == 'checkout.session.completed' && event.data.object.amount_total >= 100",
+  onEvent: async ({ event }) => {
+    const session: Stripe.Checkout.Session = event.data.object; // no cast needed
+    console.log("Checkout completed", session.id);
+  },
+});
+```
+
+- `in [...]` selects the members for any listed value, and `||` gives the union of its branches. Parentheses group branches as usual.
+- `!=`, `not in`, numeric comparisons, string operators, and `any`/`all` don't narrow. Neither do `null`, `'null'`, or `0`, because the server's `==` also matches a null field for those values.
+- Without a type clause, a field that only some members have is accepted: an event without it never matches.
+- The narrowed type also applies to the task's trigger payload, a `chat.event` action's `event` and `key`, channel connector callbacks, and a waiter's event. A filter built at runtime doesn't narrow.
 
 ## Check the result
 
@@ -83,7 +116,7 @@ event.items any ( quantity > 0 )
 
 ### Spacing
 
-Separate paths, operators, and values with one space, and put spaces inside grouping and quantifier parentheses, as in `( event.amount > 0 )` and `any ( quantity > 0 )`. Lists and quoted strings may contain spaces (`['opened', 'closed']`, `'Fix the build'`). These forms work with both the TypeScript validator and the deployment parser.
+Separate paths, operators, and values with one space. Parentheses may touch what they enclose, as in `(event.amount > 0)` and `any (quantity > 0)`. Lists and quoted strings may contain spaces (`['opened', 'closed']`, `'Fix the build'`). These forms work with both the TypeScript validator and the deployment parser.
 
 ## Filter by event type
 

package/docs/webhooks/human-in-the-loop.mdx

@@ -4,6 +4,10 @@ sidebarTitle: "Human-in-the-loop"
 description: "Pause an agent mid-turn to get a human decision from the channel (Slack approve/deny), then resume with the answer."
 ---
 
+import WebhooksBetaBanner from "/snippets/webhooks-beta-banner.mdx";
+
+<WebhooksBetaBanner />
+
 **An agent on a [channel](/webhooks/channels) can pause a turn to get a human decision, then resume once someone answers in the thread.** It posts controls into the conversation and picks up where it left off once someone clicks, with the decision merged into the turn. This is the channel counterpart of browser [human-in-the-loop](/ai-chat/patterns/human-in-the-loop): the same no-`execute` tool, but the controls live in Slack (or your own surface) instead of a React component. The [`slack()`](/webhooks/slack) connector ships Approve and Deny buttons out of the box.
 
 ## How it works
@@ -115,7 +119,9 @@ chat.channels.custom({
     text: `Approve: ${pending[0].input.action}?`,
     buttons: pending.map((c) => [`${c.toolCallId}:yes`, `${c.toolCallId}:no`]),
   }),
+  // called for every delivery: return null for anything that isn't one of these button clicks
   onInteraction: (e) => {
+    if (typeof e.buttonValue !== "string" || !e.buttonValue.includes(":")) return null;
     const [toolCallId, choice] = e.buttonValue.split(":");
     return { toolCallId, output: { approved: choice === "yes" } };
   },

package/docs/webhooks/linear.mdx

@@ -4,6 +4,10 @@ description: "Turn a chat.agent into a Linear agent: assign it an issue or @ment
 sidebarTitle: "Linear agents"
 ---
 
+import WebhooksBetaBanner from "/snippets/webhooks-beta-banner.mdx";
+
+<WebhooksBetaBanner />
+
 Linear opens an **agent session** when someone @mentions your app in an issue or delegates (assigns) an issue to it. `linear()` from `@trigger.dev/linear` is a [channel](/webhooks/channels) connector for those sessions: each one becomes a durable Trigger.dev [session](/ai-chat/sessions), the user's prompt runs as a turn, and the agent's work shows up in Linear as thoughts, actions, a plan, an approval card when it needs a decision, and a response when it is done.
 
 ```ts
@@ -44,7 +48,7 @@ The `run()` loop is the same one a browser chat or a Slack thread uses. Verifica
 
 ## What the agent sees
 
-On the first turn of a session the connector frames Linear's payload for the model: who summoned it and on which issue, the workspace **guidance** rules for agents, Linear's formatted **issue context** (title, description, labels, project, comments), and the comment that mentioned it. An assignment with no comment reads as "assigned ENG-412 to you". Prior comments on the issue are [seeded](/webhooks/channels#joining-a-thread-that-already-has-messages) as transcript messages, so the agent can answer with the context a reader of the issue has.
+On the first turn of a session the connector frames Linear's payload for the model: who summoned it and on which issue, the workspace **guidance** rules for agents, Linear's formatted **issue context** (title, description, labels, project, comments), and the comment that mentioned it. An assignment with no comment reads as "assigned ENG-412 to you". Prior comments on the issue are seeded as transcript messages, so the agent can answer with the context a reader of the issue has.
 
 A follow-up prompt on the session is just the message. If the user hits **Stop** in Linear, see [Stopping](#stopping).
 
@@ -164,8 +168,8 @@ The first Linear turn binds the session to the agent session ([bound sessions](/
 | `endpoint` | endpoint | The Linear endpoint, declared with `webhooks.endpoint.define({ id, source: webhookSource() })`. Other `webhook()` tasks can subscribe to the same endpoint. |
 | `token` | `string` or resolver | The app's OAuth access token, or a function of the event (keyed on `organizationId`) for multi-workspace installs. |
 | `key` | `string` | Session [key](/webhooks/session-routing) template over `{event.*}`, `{header.*}` and `{webhook.*}`. Defaults to one session per Linear agent session. |
-| `filter` | `string` | Extra [filter](/webhooks/filters), composed with the built-in agent-session guard. |
-| `startOn` | `string` | Only start a session when the event matches. Existing sessions always resume. |
+| `filter` | filter string | Extra [filter](/webhooks/filters), composed with the built-in agent-session guard. Checked against the endpoint's event type, like `webhook()`'s `filter`. |
+| `startOn` | filter string | Only start a session when the event matches. Existing sessions always resume. Checked against the endpoint's event type. |
 | `context` | `{ guidance?, promptContext?, previousComments? }` | What from Linear's payload is put in front of the model on the first turn. All on by default. |
 | `progress` | `"actions"` or `"off"` | Mirror tool calls as action activities (default) or post only the response. |
 | `summarize` | `boolean` | Set the session title from each response's first line. Off by default; Linear titles the session itself. |

package/docs/webhooks/overview.mdx

@@ -4,6 +4,10 @@ description: "Receive provider webhooks on hosted, verified endpoints and route
 sidebarTitle: "Overview"
 ---
 
+import WebhooksBetaBanner from "/snippets/webhooks-beta-banner.mdx";
+
+<WebhooksBetaBanner />
+
 **A webhook endpoint is one hosted URL that you register with a provider.** Trigger.dev verifies every request against the endpoint's [source](/webhooks/sources), records it as a [delivery](/webhooks/deliveries), and hands the event to everything subscribed to the endpoint.
 
 Declare the endpoint once, then subscribe to it:

package/docs/webhooks/session-routing.mdx

@@ -4,6 +4,10 @@ description: "Route verified webhook deliveries to a durable per-key session ins
 sidebarTitle: "Session routing"
 ---
 
+import WebhooksBetaBanner from "/snippets/webhooks-beta-banner.mdx";
+
+<WebhooksBetaBanner />
+
 A plain [`webhook()`](/webhooks/overview) runs a fresh, stateless run for every delivery. Sometimes you want the opposite: deliveries that share a key (a customer, an installation, an issue) should land on **one durable [session](/ai-chat/sessions)** and be handled in order, with state carried across them. That is what session routing does.
 
 Instead of a handler, you declare a `chat.event` on an [endpoint](/webhooks/overview) and list it on an agent. The verified delivery is routed to a find-or-created session and arrives as an [action](/ai-chat/actions).
@@ -23,6 +27,8 @@ export const orderEvents = chat.event({
   endpoint: stripe,
   // one session per customer
   key: "{event.data.object.customer}",
+  // invoices always carry a customer; events without one would have no session to go to
+  filter: "event.type startsWith 'invoice.'",
   type: "order.event",
 });
 ```
@@ -113,7 +119,7 @@ A bound turn posts the final answer as a fresh message in the thread (no placeho
 
 Listing a descriptor on an agent subscribes that agent to the descriptor's endpoint, with the subscriber id `agentId:eventId`. If two agents list the same descriptor, the endpoint has two subscribers and every delivery goes to both, on the one URL the provider already knows.
 
-A session belongs to the agent that created it. When two agents compute the same key, the second agent's delivery to that session fails with an error naming the owner, so give each agent a key that can't collide, for example by prefixing `{webhook.id}` or a constant.
+A session belongs to the agent that created it. When two agents compute the same key, the second agent's delivery to that session fails with an error naming the owner. Both agents see the same endpoint, so a `{webhook.*}` placeholder resolves the same for each and can't separate them. Give each agent its own descriptor with a constant prefix in the key instead, for example `"billing-{event.data.object.customer}"` and `"support-{event.data.object.customer}"`.
 
 An exported `chat.event` that no agent lists routes nothing. `trigger dev` warns about it (it is not an error, since declaring the descriptor before wiring the agent is a normal step), so wire it onto an agent once you are ready.
 

package/docs/webhooks/slack.mdx

@@ -4,6 +4,10 @@ description: "Turn a chat.agent into a Slack agent: users message it in Slack, i
 sidebarTitle: "Slack agents"
 ---
 
+import WebhooksBetaBanner from "/snippets/webhooks-beta-banner.mdx";
+
+<WebhooksBetaBanner />
+
 **`slack()` from `@trigger.dev/slack` turns a `chat.agent` into a native Slack agent.** Each Slack agent session (a conversation with the agent, or a thread in a channel) becomes a durable Trigger.dev [session](/ai-chat/sessions). A message runs as a turn, the session shows the agent working, the reply streams into the thread as the model writes it, and Slack's stop button stops the turn.
 
 ```ts /trigger/support.ts
@@ -209,11 +213,15 @@ export const support = chat.agent({
 });
 ```
 
-`onAction` also gets the click itself as `channel.event`, typed with `SlackBlockActions`: who clicked, and the message the button was on. An action doesn't have to answer; return nothing to only do work:
+`onAction` also gets the click itself as `channel.event`, typed with `SlackBlockActions`: who clicked, and the message the button was on. An action doesn't have to answer; return nothing to only do work. Here `actionSchema` accepts a `pick` action alongside `ask`:
 
 ```ts
 import type { SlackBlockActions } from "@trigger.dev/slack";
 
+actionSchema: z.discriminatedUnion("type", [
+  z.object({ type: z.literal("ask"), question: z.string() }),
+  z.object({ type: z.literal("pick"), name: z.string() }),
+]),
 onAction: async ({ action, channel }) => {
   const click = channel?.event as SlackBlockActions | undefined;
   if (action.type === "pick") {
@@ -244,7 +252,7 @@ import { slack, mentions } from "@trigger.dev/slack";
 slack({ id: "slack", endpoint: slackEvents, token, startOn: mentions("U012BOT") });
 ```
 
-When someone mentions the agent partway through a thread, `seedFromThread: true` loads the thread's earlier replies into the new session first, so the agent answers with the context a reader of the thread has. It reads `conversations.replies` once, on the session's first turn, and keeps the newest 50 replies (`{ limit }` changes that). New non-Marketplace apps are limited by Slack to 15 replies per call and one call a minute; a rate limit keeps what was fetched rather than failing the turn.
+When someone mentions the agent partway through a thread, `seedFromThread: true` loads the thread's earlier replies into the new session first, so the agent answers with the context a reader of the thread has. It loads the history once, on the session's first turn, paging through `conversations.replies` and keeping the newest 50 replies (`{ limit }` changes that). Slack limits new commercially distributed apps outside the Marketplace to 15 replies per call and one call a minute, so such an app may only get the thread's first page; internal apps keep the normal limits. A rate limit keeps what was fetched rather than failing the turn.
 
 ## Messages sent while the agent is working
 
@@ -349,8 +357,8 @@ slack({
 | `delivery` | `"stream"` or `"final"` | `"stream"` (default) streams the reply natively. `"final"` posts it once when the turn ends. |
 | `title` | `(prompt, event) => string \| null` | The session title, set on its first turn. Defaults to the first line of the prompt. |
 | `progress` | `"tasks"` or `"off"` | Tool calls as task cards in the streamed reply. Default `"tasks"`. |
-| `startOn` | `string` | Only start a session in a channel when the event matches (see `mentions`). Existing sessions always resume, and the agent's own conversation always starts one. |
-| `filter` | `string` | Extra [filter](/webhooks/filters) for message events, composed with the built-in guard that drops the bot's own messages. |
+| `startOn` | filter string | Only start a session in a channel when the event matches (see `mentions`). Existing sessions always resume, and the agent's own conversation always starts one. Checked against the endpoint's event type. |
+| `filter` | filter string | Extra [filter](/webhooks/filters) for message events, composed with the built-in guard that drops the bot's own messages. Checked against the endpoint's event type, like `webhook()`'s `filter`. |
 | `key` | `string` | Session [key](/webhooks/session-routing) template. Defaults to one session per thread. |
 | `seedFromThread` | `boolean` or `{ limit }` | Load a thread's earlier replies into a new session. Off by default. |
 | `approval` | `(call, { button }) => message` | The UI for a tool with no `execute`. Defaults to Approve and Deny resolving to `{ approved }`. |

package/docs/webhooks/sources.mdx

@@ -4,6 +4,10 @@ description: "Choose an endpoint's source, configure verification, and type the
 sidebarTitle: "Sources & verification"
 ---
 
+import WebhooksBetaBanner from "/snippets/webhooks-beta-banner.mdx";
+
+<WebhooksBetaBanner />
+
 An endpoint's `source` defines how Trigger.dev verifies requests and types the event every subscriber receives. Choose a named provider source or supply a verification configuration with `webhooks.custom()`.
 
 ## Presets

package/docs/webhooks/waiters.mdx

@@ -4,6 +4,10 @@ description: "Pause a run until a matching webhook arrives on an endpoint, then
 sidebarTitle: "Waiters"
 ---
 
+import WebhooksBetaBanner from "/snippets/webhooks-beta-banner.mdx";
+
+<WebhooksBetaBanner />
+
 **A waiter pauses a run until a matching delivery arrives on an [endpoint](/webhooks/overview).** Use it when your task starts something in another system and needs to know when that system reports back: a payment that settles, a build that finishes, a document that gets signed.
 
 ```ts /trigger/checkout.ts
@@ -12,7 +16,15 @@ import { stripe } from "./stripe"; // webhooks.endpoint.define({ id: "stripe", s
 
 export const checkout = task({
   id: "checkout",
-  run: async ({ orderId }: { orderId: string }) => {
+  run: async ({
+    orderId,
+    customerId,
+    paymentMethodId,
+  }: {
+    orderId: string;
+    customerId: string;
+    paymentMethodId: string;
+  }) => {
     const waiter = await webhooks.waiter.create(stripe, {
       match: {
         "event.type": "payment_intent.succeeded",
@@ -23,7 +35,19 @@ export const checkout = task({
       idempotencyKey: `payment-${orderId}`,
     });
 
-    await stripeClient.paymentIntents.create({ amount: 4200, currency: "usd", metadata: { orderId } });
+    // confirm: true charges the customer's saved payment method now, so Stripe sends payment_intent.succeeded.
+    // Stripe's own idempotency key stops a retry from creating a second intent for the order.
+    await stripeClient.paymentIntents.create(
+      {
+        amount: 4200,
+        currency: "usd",
+        customer: customerId,
+        payment_method: paymentMethodId,
+        confirm: true,
+        metadata: { orderId },
+      },
+      { idempotencyKey: `payment-intent-${orderId}` }
+    );
 
     const { event, deliveryId } = await webhooks.waiter.wait(waiter).unwrap();
     return { paymentIntent: event.data.object.id, deliveryId };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigger.dev/sdk",
-  "version": "4.8.0-webhooks.20261015065339",
+  "version": "4.8.0-webhooks.20261020092920",
   "description": "trigger.dev Node.JS SDK",
   "license": "MIT",
   "publishConfig": {
@@ -69,12 +69,13 @@
   "dependencies": {
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/semantic-conventions": "1.41.1",
-    "@trigger.dev/core": "4.8.0-webhooks.20261015065339",
+    "@trigger.dev/core": "4.8.0-webhooks.20261020092920",
     "uncrypto": "^0.1.3"
   },
   "devDependencies": {
     "@ai-sdk/provider": "3.0.8",
     "@arethetypeswrong/cli": "^0.18.5",
+    "@opentelemetry/sdk-trace-base": "2.8.0",
     "@types/react": "^19.2.14",
     "ai": "^6.0.116",
     "ai-v7": "npm:ai@7.0.0-canary.159",