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

package/docs/webhooks/overview.mdx

@@ -4,10 +4,6 @@ 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:
@@ -63,6 +59,22 @@ Each subscriber has its own [filter](/webhooks/filters), so one delivery can rea
 | `endpoint` | The endpoint the delivery arrived on: `id`, `declaredId`, `tenantId`, `externalRef`, and the `metadata` you declared. |
 | `ctx` | The same [run context](/context) that regular tasks receive. |
 
+`webhook()` also takes the options a [task](/tasks/overview) does, such as `queue`, `concurrency`, `machine`, `retry`, `maxDuration` and the lifecycle hooks. For example, to handle one delivery at a time:
+
+```ts
+export const orders = webhook({
+  id: "stripe-orders",
+  endpoint: stripe,
+  queue: { concurrencyLimit: 1 },
+  retry: { maxAttempts: 5 },
+  onEvent: async ({ event }) => {
+    // ...
+  },
+});
+```
+
+The limit covers every delivery the task handles. To process each customer's events in order while different customers run in parallel, route them to an agent with [session routing](/webhooks/session-routing): deliveries with the same key land in one session and are handled one after another.
+
 `webhooks.endpoint.define` also takes a `description` and `metadata`. The metadata is passed to every subscriber as `endpoint.metadata`. The endpoint `id` can't start with `wh_`, which is reserved for the ids Trigger.dev generates.
 
 ## How it works

package/docs/webhooks/session-routing.mdx

@@ -4,10 +4,6 @@ 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).
@@ -87,7 +83,14 @@ When the same session is also a [channel](/webhooks/channels) conversation (a Sl
 ```ts
 export const orderAgent = chat.agent({
   id: "order-agent",
-  channels: [slack({ id: "support-slack", endpoint: slackEvents, token: process.env.SLACK_BOT_TOKEN! })],
+  channels: [
+    slack({
+      id: "support-slack",
+      endpoint: slackEvents,
+      token: process.env.SLACK_BOT_TOKEN!,
+      startOn: appMentions(),
+    }),
+  ],
   events: [orderEvents],
   onAction: async ({ action }) => {
     if (action.type === "order.event") {

package/docs/webhooks/slack.mdx

@@ -1,26 +1,29 @@
 ---
 title: "Slack agents"
-description: "Turn a chat.agent into a Slack agent: users message it in Slack, it shows its status while it works, streams its reply with tool calls as task cards, asks for approvals, and stops on Slack's stop button."
+description: "Turn a chat.agent into a Slack agent: users message it in Slack, it shows its status while it works, streams its reply with its tool calls as a plan, asks for approvals, and stops on Slack's stop button."
 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
 import { webhooks } from "@trigger.dev/sdk";
 import { chat } from "@trigger.dev/sdk/ai";
-import { slack, webhookSource } from "@trigger.dev/slack";
+import { appMentions, slack, webhookSource } from "@trigger.dev/slack";
 import { anthropic } from "@ai-sdk/anthropic";
 
 const slackEvents = webhooks.endpoint.define({ id: "slack", source: webhookSource() });
 
 export const support = chat.agent({
   id: "support",
-  channels: [slack({ id: "slack", endpoint: slackEvents, token: process.env.SLACK_BOT_TOKEN! })],
+  channels: [
+    slack({
+      id: "slack",
+      endpoint: slackEvents,
+      token: process.env.SLACK_BOT_TOKEN!,
+      startOn: appMentions(),
+    }),
+  ],
   tools: { searchDocs, refundOrder },
   run: async ({ messages, tools, signal, streamText }) =>
     streamText({ model: anthropic("claude-sonnet-4-5"), messages, tools, abortSignal: signal }),
@@ -58,6 +61,7 @@ export const support = chat.agent({
           - files:read
           - reactions:write
           - im:history
+          - app_mentions:read
           - channels:history
           - groups:history
     settings:
@@ -65,6 +69,7 @@ export const support = chat.agent({
         request_url: https://your-endpoint-url
         bot_events:
           - message.im
+          - app_mention
           - message.channels
           - message.groups
           - agent_session_stopped
@@ -73,7 +78,7 @@ export const support = chat.agent({
         request_url: https://your-endpoint-url
     ```
 
-    `agent_view` makes the app an agent, `agent_session_stopped` turns on the stop button, interactivity delivers clicks on the agent's buttons, `files:read` lets the agent read the images and PDFs users share with it, and `reactions:write` lets it mark a message it picked up mid-reply. Drop `message.channels`, `message.groups` and their `history` scopes if the agent should only answer in its own conversations.
+    `agent_view` makes the app an agent, `agent_session_stopped` turns on the stop button, interactivity delivers clicks on the agent's buttons, `files:read` lets the agent read the images and PDFs users share with it, `reactions:write` lets it mark a message it picked up mid-reply, and `app_mention` with `app_mentions:read` lets an @mention start a session in a channel (see [Channel threads](#channel-threads)). Drop `app_mention`, `message.channels`, `message.groups` and their scopes if the agent should only answer in its own conversations.
   </Step>
   <Step title="Connect the endpoint">
     Paste the app's **Signing Secret** (Basic Information, App Credentials) as the endpoint's signing secret. Until it is set the endpoint rejects Slack's signed requests, so Slack shows the request URL as not verified: once the secret is in, click **Verify** on the app's Event Subscriptions page (or **Click here to verify** on the App Manifest page). Install the app to your workspace and pass the bot token (`xoxb-...`) as `token`. The endpoint's setup prompt walks an AI coding agent through these settings.
@@ -89,18 +94,20 @@ export const support = chat.agent({
 | --- | --- |
 | A turn starts | The session's status is **processing**. On the first turn the session is titled with the prompt. |
 | The model writes | The reply streams into the thread with `chat.startStream`, `chat.appendStream` and `chat.stopStream`, as markdown. |
-| A tool is called | A task card in the reply, marked complete when the tool returns and failed if it throws. |
+| A tool is called | A task in the reply's plan, titled by the tool's `title` (or its name made readable), marked complete when the tool returns and failed if it throws. The plan reads "Working on it", then "Done", "Stopped" or "Waiting for approval" when the turn ends. |
 | A tool needs a decision | Approve and Deny buttons, and the status is **suspended** (see [Approvals and buttons](#approvals-and-buttons)). |
+| The turn fails | The reply ends with "Something went wrong answering this. Try again." (`errorMessage` changes it). The error is logged on the run. |
 | The turn ends | The status goes back to **active**, whether it answered, stopped, failed or had nothing to say. |
 | `chat.close()` | The status is **closed**. |
 
-Set `title` to name the session yourself; return null to keep Slack's own. A title the user sets in Slack is never overwritten. Slack drops a processing status after an hour, so a longer turn re-sends it every 50 minutes. `progress: "off"` streams the reply without task cards, and `delivery: "final"` posts the whole reply once the turn ends instead of streaming it.
+Set `title` to name the session yourself; return null to keep Slack's own. A title the user sets in Slack is never overwritten. Slack drops a processing status after an hour, so a longer turn re-sends it every 50 minutes. Give a tool a readable task title with the AI SDK's `tool({ title: "Search the archive", ... })`; without one the task shows the tool's name made readable (`searchArchive` shows "Search archive"). `progress: "tasks"` shows one task card per call between the reply's text instead of a plan, `progress: "off"` streams the reply without them, and `delivery: "final"` posts the whole reply once the turn ends instead of streaming it.
 
 ```ts
 slack({
   id: "slack",
   endpoint: slackEvents,
   token,
+  startOn: appMentions(),
   title: (prompt) => `Support: ${prompt.slice(0, 80)}`,
 });
 ```
@@ -118,6 +125,7 @@ slack({
   id: "slack",
   endpoint: slackEvents,
   token,
+  startOn: appMentions(),
   approval: (call, { button }) => ({
     text: `Run ${call.toolName}?`,
     blocks: [
@@ -144,6 +152,7 @@ export const moji = chat.agent({
       id: "slack",
       endpoint: slackEvents,
       token,
+      startOn: appMentions(),
       interactions: {
         pickEmoji: (call, { button }) => {
           const { options } = call.input as { options: { name: string }[] };
@@ -181,18 +190,18 @@ The click resolves `pickEmoji` to `{ picked: "wizard" }`, the buttons collapse t
 Buttons that aren't answering a tool, such as follow-up questions, are built with `slackButton()` and posted with the surface's `post()`. A click reaches `onAction`, validated against `actionSchema` like a browser action, and returning `chat.turn(message)` answers it in the thread:
 
 ```ts
-import { slackButton, type SlackSurface } from "@trigger.dev/slack";
+import { slackButton, type SlackRunSurface } from "@trigger.dev/slack";
 
 export const support = chat.agent({
   id: "support",
-  channels: [slack({ id: "slack", endpoint: slackEvents, token })],
+  channels: [slack({ id: "slack", endpoint: slackEvents, token, startOn: appMentions() })],
   actionSchema: z.object({ type: z.literal("ask"), question: z.string() }),
   tools: {
     offerFollowUps: tool({
       description: "Offer the user up to three follow-up questions as buttons",
       inputSchema: z.object({ questions: z.array(z.string()).max(3) }),
       execute: async ({ questions }) => {
-        await chat.surface<SlackSurface>()?.post({
+        await chat.surface<SlackRunSurface>()?.post({
           text: "Follow-up questions",
           blocks: [
             {
@@ -244,14 +253,27 @@ Slack shows a stop button while the agent is working. It aborts the running turn
 
 ## Channel threads
 
-In a channel the agent answers every thread it can see. To have it answer only when it is @mentioned, pass `startOn` with the `mentions` helper and your bot's user id. A mention in a channel starts a session and the agent answers in a thread under it, then follows the rest of that thread without being mentioned again. `startOn` only applies to channels: a message in the agent's own conversation always starts a session.
+`startOn` is required: it decides which channel messages start a session. Pass `appMentions()` to have the agent answer only when it is @mentioned. A mention in a channel starts a session and the agent answers in a thread under it, then follows the rest of that thread without being mentioned again. `startOn` only applies to channels: a message in the agent's own conversation always starts a session.
 
 ```ts
-import { slack, mentions } from "@trigger.dev/slack";
+import { slack, appMentions } from "@trigger.dev/slack";
 
-slack({ id: "slack", endpoint: slackEvents, token, startOn: mentions("U012BOT") });
+slack({ id: "slack", endpoint: slackEvents, token, startOn: appMentions() });
 ```
 
+`appMentions()` uses Slack's `app_mention` event, so the app needs the `app_mention` bot event and the `app_mentions:read` scope (both in the manifest above), and no bot user id. Slack also delivers each mention as an ordinary channel message; the connector ignores that copy, so one mention runs one turn.
+
+What each value does:
+
+| `startOn` | The agent starts a session in a channel |
+| --- | --- |
+| `appMentions()` | When it is @mentioned (recommended). |
+| `mentions("U012BOT")` | When a message mentions that bot user id, from message events, without the `app_mention` subscription. |
+| `"event.event.type == 'message'"` | On every message it can see. |
+| `"event.event.channel_type == 'im'"` | Never: it answers only in its own conversation. |
+
+In a channel shared with another organization through Slack Connect, pass `ownWorkspaceOnly: true` to answer only people from your own workspace. Messages, mentions and button clicks from the other organization's users are dropped before they reach the agent. In Enterprise Grid this also drops users whose home workspace is another workspace in the org.
+
 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
@@ -261,7 +283,7 @@ A message sent while the agent is still answering gets 👀 as soon as it arrive
 ```ts
 export const support = chat.agent({
   id: "support",
-  channels: [slack({ id: "slack", endpoint: slackEvents, token })],
+  channels: [slack({ id: "slack", endpoint: slackEvents, token, startOn: appMentions() })],
   pendingMessages: { shouldInject: () => true },
   run: async ({ messages, signal, streamText }) =>
     streamText({ model, messages, abortSignal: signal, stopWhen: stepCountIs(10) }),
@@ -336,6 +358,7 @@ slack({
   id: "slack",
   endpoint: slackEvents,
   token,
+  startOn: appMentions(),
   delivery: "final",
   outbound: (reply) =>
     reply.text
@@ -356,13 +379,15 @@ slack({
 | `token` | `string` or resolver | Bot token (`xoxb-...`), or a function of the event (its `team_id`) for multi-workspace apps. |
 | `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` | 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. |
+| `progress` | `"plan"`, `"tasks"` or `"off"` | How tool calls show in the streamed reply: one plan block (default), a task card per call, or none. Task titles come from each tool's `title`. |
+| `startOn` | filter string | Required. Which channel messages start a session, usually `appMentions()` (see [Channel threads](#channel-threads)). 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 }`. |
 | `interactions` | `{ [toolName]: (call, { button }) => message }` | A tool's own UI; a click resolves the tool with the button's `output`. |
 | `receivedReaction` | `string \| null` | Emoji added, on arrival, to a message sent while the agent is answering. Default `"eyes"`, null for none. |
+| `errorMessage` | `string \| (ctx) => string` | What the reply shows when a turn fails, fixed or built from the failure ([details](/webhooks/channels#when-a-turn-fails)). Default "Something went wrong answering this. Try again." |
+| `ownWorkspaceOnly` | `boolean` | Drop messages, mentions and button clicks from people outside the app's workspace, such as Slack Connect guests. Off by default. |
 | `inbound` / `outbound` | functions | Map a Slack event to the turn, and a posted reply to a Slack message. |
 | `apiBaseUrl` | `string` | Override the Slack Web API base, for testing against a mock. |

package/docs/webhooks/sources.mdx

@@ -4,10 +4,6 @@ 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
@@ -96,16 +92,49 @@ Each function below returns a source with its provider's verification configurat
 
 | Verification | Source functions |
 | --- | --- |
-| Svix | `clerk()`, `resend()`, `brex()` |
-| Standard Webhooks | `openai()`, `replicate()`, `recallai()`, `composio()` |
+| Svix | `clerk()`, `resend()`, `brex()`, `autumn()` |
+| Standard Webhooks | `openai()`, `replicate()`, `recallai()`, `composio()`, `loops()`, `granola()` |
 | HMAC-SHA256 with `X-Hub-Signature-256` | `whatsapp()` |
 | Shared secret in `X-Gitlab-Token` | `gitlab()` |
-| Provider-specific HMAC | `calendly()`, `calCom()`, `sentry()`, `pagerduty()`, `vercel()`, `linear()`, `notion()`, `typeform()`, `docusign()`, `jira()`, `intercom()`, `zendesk()`, `attio()`, `workos()`, `elevenlabs()`, `vapi()`, `retell()`, `shopify()` |
+| Shared secret as `Authorization: Bearer` | `supabase()` |
+| Hookdeck relay (HMAC-SHA256 with `X-Hookdeck-Signature`) | `hookdeck()` |
+| Provider-specific HMAC | `calendly()`, `calCom()`, `sentry()`, `pagerduty()`, `vercel()`, `linear()`, `notion()`, `typeform()`, `docusign()`, `jira()`, `intercom()`, `zendesk()`, `attio()`, `workos()`, `elevenlabs()`, `vapi()`, `retell()`, `shopify()`, `metronome()`, `mux()`, `tailscale()`, `langfuse()`, `infisical()`, `planetscale()`, `plain()`, `firecrawl()` |
 
 Provider IDs containing a hyphen use a camel case function name: the `cal-com` provider is `webhooks.calCom()`.
 
+Supabase database webhooks aren't signed, so `supabase()` checks a shared secret instead. Generate the endpoint's secret on Trigger.dev, then add an `Authorization` header with the value `Bearer <secret>` under the webhook's HTTP Headers in Supabase.
+
 Slack also ships as a chat channel in `@trigger.dev/slack`.
 
+### 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:
+
+```ts /trigger/stripe-via-hookdeck.ts
+import type Stripe from "stripe";
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const stripeViaHookdeck = webhooks.endpoint.define({
+  id: "stripe-via-hookdeck",
+  source: webhooks.hookdeck<Stripe.Event>(),
+});
+
+export const paymentSucceeded = webhook({
+  id: "payment-succeeded",
+  endpoint: stripeViaHookdeck,
+  filter: "event.type == 'payment_intent.succeeded'",
+  onEvent: async ({ event }) => {
+    console.log(event.id);
+  },
+});
+```
+
+Use the endpoint URL as the connection's HTTP destination, keep the destination's authentication on Hookdeck Signature (the default for new destinations), and store the Hookdeck project's signing secret from **Settings > Secrets** as the endpoint's signing secret.
+
+- **Secret rotation:** when you roll the signing secret in Hookdeck with an expiry, Hookdeck also signs each request with the previous secret in `X-Hookdeck-Signature-2`, so deliveries keep verifying until you store the new secret.
+- **Deduplication:** retries dedupe on `X-Hookdeck-Eventid`, which is the same on every attempt of a Hookdeck event.
+- **Custom header prefix:** if you changed the header prefix in the Hookdeck project's settings, pass it with `webhooks.hookdeck({ headerPrefix: "x-acme" })`. The prefix renames the event id header; the signature headers keep the `X-Hookdeck-` name.
+
 ## Endpoint validation
 
 Some sources also define a response for the provider's endpoint-validation request. These requests don't create deliveries or task runs.

package/docs/webhooks/waiters.mdx

@@ -4,10 +4,6 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigger.dev/sdk",
-  "version": "4.8.0-webhooks.20261020092920",
+  "version": "4.8.0",
   "description": "trigger.dev Node.JS SDK",
   "license": "MIT",
   "publishConfig": {
@@ -69,7 +69,7 @@
   "dependencies": {
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/semantic-conventions": "1.41.1",
-    "@trigger.dev/core": "4.8.0-webhooks.20261020092920",
+    "@trigger.dev/core": "4.8.0",
     "uncrypto": "^0.1.3"
   },
   "devDependencies": {