@trigger.dev/sdk 0.0.0-python-preview-20250226140121 → 0.0.0-rc-4-8-0-20261021151928

package/docs/webhooks/slack.mdx

@@ -0,0 +1,393 @@
+---
+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 its tool calls as a plan, asks for approvals, and stops on Slack's stop button."
+sidebarTitle: "Slack agents"
+---
+
+**`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 { 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!,
+      startOn: appMentions(),
+    }),
+  ],
+  tools: { searchDocs, refundOrder },
+  run: async ({ messages, tools, signal, streamText }) =>
+    streamText({ model: anthropic("claude-sonnet-4-5"), messages, tools, abortSignal: signal }),
+});
+```
+
+`run()` is the same function that answers a browser chat or a [Linear session](/webhooks/linear). Signature verification, Slack's `url_verification` handshake, retry dedup, per-thread state, status updates and streaming are handled by the connector.
+
+## Setup
+
+<Steps>
+  <Step title="Deploy the agent">
+    Declare the endpoint with `webhookSource()` from `@trigger.dev/slack` and pass it to `slack({ endpoint })`. Deploying registers the hosted [endpoint](/webhooks/connect) and gives you its URL.
+  </Step>
+  <Step title="Create the Slack app from a manifest">
+    At [api.slack.com/apps](https://api.slack.com/apps), create an app **From a manifest** and paste this, with the endpoint's URL in both request URLs:
+
+    ```yaml manifest.yaml
+    display_information:
+      name: Support Agent
+    features:
+      bot_user:
+        display_name: Support Agent
+        always_online: true
+      app_home:
+        messages_tab_enabled: true
+        messages_tab_read_only_enabled: false
+      agent_view:
+        agent_description: Answers support questions and handles refunds.
+    oauth_config:
+      scopes:
+        bot:
+          - assistant:write
+          - chat:write
+          - files:read
+          - reactions:write
+          - im:history
+          - app_mentions:read
+          - channels:history
+          - groups:history
+    settings:
+      event_subscriptions:
+        request_url: https://your-endpoint-url
+        bot_events:
+          - message.im
+          - app_mention
+          - message.channels
+          - message.groups
+          - agent_session_stopped
+      interactivity:
+        is_enabled: true
+        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, `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.
+  </Step>
+  <Step title="Try it">
+    Open the agent in Slack and send it a message. The session shows it working within a second, and the reply streams in. In a channel, invite the bot (`/invite @Support Agent`) and message it in a thread.
+  </Step>
+</Steps>
+
+## What Slack shows
+
+| Moment | In Slack |
+| --- | --- |
+| 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 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. 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)}`,
+});
+```
+
+If a streaming request fails in a way that leaves its outcome unknown (a timeout or a dropped connection), the connector does not retry it, since Slack may already have shown that text. It closes the stream and posts the rest of the reply as its own message, so nothing is lost, at the cost of possibly repeating one batch. If that post fails too, the whole reply is posted again as a normal message. Rate limits wait out `Retry-After` and resend the same batch. If the worker running a turn dies mid-stream, the next worker closes that stream with a short "Interrupted" note before it picks the conversation back up.
+
+## Approvals and buttons
+
+A tool with no `execute` pauses the turn until the user answers it in Slack. By default `slack()` posts Approve and Deny buttons, and a click resolves the tool to `{ approved: boolean }`, collapses the buttons to the decision and resumes the turn. See [human-in-the-loop](/webhooks/human-in-the-loop) for the tool definition.
+
+`approval` replaces those buttons for every such tool. Build buttons with `button()`, whose `output` is what the click resolves the tool to:
+
+```ts
+slack({
+  id: "slack",
+  endpoint: slackEvents,
+  token,
+  startOn: appMentions(),
+  approval: (call, { button }) => ({
+    text: `Run ${call.toolName}?`,
+    blocks: [
+      { type: "section", text: { type: "mrkdwn", text: `Run \`${call.toolName}\`?` } },
+      {
+        type: "actions",
+        elements: [
+          button({ text: "Ship it", style: "primary", output: { approved: true } }),
+          button({ text: "Not now", output: { approved: false } }),
+        ],
+      },
+    ],
+  }),
+});
+```
+
+`interactions` gives a single tool its own UI, keyed by tool name, so a tool can ask the user to pick, rate or choose and continue with the answer:
+
+```ts
+export const moji = chat.agent({
+  id: "moji",
+  channels: [
+    slack({
+      id: "slack",
+      endpoint: slackEvents,
+      token,
+      startOn: appMentions(),
+      interactions: {
+        pickEmoji: (call, { button }) => {
+          const { options } = call.input as { options: { name: string }[] };
+          return {
+            text: "Pick one",
+            blocks: [
+              { type: "section", text: { type: "mrkdwn", text: "Which one should I add?" } },
+              {
+                type: "actions",
+                elements: options.map((o) => button({ text: `:${o.name}:`, output: { picked: o.name } })),
+              },
+            ],
+          };
+        },
+      },
+    }),
+  ],
+  tools: {
+    pickEmoji: tool({
+      description: "Ask the user to pick one of the generated emoji",
+      inputSchema: z.object({ options: z.array(z.object({ name: z.string() })) }),
+      outputSchema: z.object({ picked: z.string() }),
+    }),
+    addEmoji,
+  },
+  run: async ({ messages, tools, signal, streamText }) =>
+    streamText({ model, messages, tools, abortSignal: signal, stopWhen: stepCountIs(10) }),
+});
+```
+
+The click resolves `pickEmoji` to `{ picked: "wizard" }`, the buttons collapse to the choice, and the turn continues.
+
+### Buttons that send the agent an action
+
+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 SlackRunSurface } from "@trigger.dev/slack";
+
+export const support = chat.agent({
+  id: "support",
+  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<SlackRunSurface>()?.post({
+          text: "Follow-up questions",
+          blocks: [
+            {
+              type: "actions",
+              elements: questions.map((question) =>
+                slackButton({ text: question, action: { type: "ask", question } })
+              ),
+            },
+          ],
+        });
+        return "offered";
+      },
+    }),
+  },
+  onAction: async ({ action }) => chat.turn(action.question),
+  run: async ({ messages, tools, signal, streamText }) =>
+    streamText({ model, messages, tools, abortSignal: signal, stopWhen: stepCountIs(10) }),
+});
+```
+
+`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") {
+    await addEmoji.trigger({ name: action.name, pickedBy: click?.user?.id });
+    return; // no turn
+  }
+  return chat.turn(action.question);
+},
+```
+
+Only buttons built with `button()` or `slackButton()` reach the agent. Buttons your own code builds by hand go to a [`webhook()`](/webhooks/overview) subscribed to the same endpoint, and never start a turn.
+
+## Stopping
+
+Slack shows a stop button while the agent is working. It aborts the running turn through the run's `signal`, exactly like a browser chat's stop: the model call and any tool that honours the signal stop, the partial reply stays in the thread, and the status goes back to active. The next message continues the conversation.
+
+- A stop pressed while nothing is running does nothing, and a repeated or delayed stop never stops a later turn.
+- A stop that reaches a session waiting on an approval cancels it: the buttons are replaced with "Stopped", the pending tool call is recorded as stopped so the model sees that on the next turn, and a later click resumes nothing.
+- Stopping cannot undo what already happened. A tool that finished before the stop has had its effect.
+
+## Channel threads
+
+`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, appMentions } from "@trigger.dev/slack";
+
+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
+
+A message sent while the agent is still answering gets 👀 as soon as it arrives, so the user knows it was seen (`receivedReaction` changes the emoji, null turns it off). It then waits and runs as the next turn, in the order messages arrived. With [`pendingMessages`](/ai-chat/pending-messages) on the agent, it can be folded into the reply the agent is already writing instead: `shouldInject` decides at each step, and the message reaches the model before its next step. A message `shouldInject` declines still runs as its own turn.
+
+```ts
+export const support = chat.agent({
+  id: "support",
+  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) }),
+});
+```
+
+A message is only folded in at a step boundary, so a reply that is one long model step with no tool calls finishes first and the message runs next. The stop button and button clicks are never folded in.
+
+## Files
+
+Images (PNG, JPEG, GIF, WebP) and PDFs that a user shares in the conversation reach the model with their message, including a file sent with no text. The transcript keeps each file's Slack URL, and the `streamText` given to `run()` downloads it with the bot token when the model reads it, once per run. An image over 5 MB is sent as its largest Slack thumbnail.
+
+Other file types, files over 20 MB, and files the app can't read (deleted, or shared from another workspace) reach the model as a one-line note naming the file, so it can say it can't open them. A file that is deleted after it was shared becomes the same note on later turns, and the conversation carries on.
+
+A custom `inbound` keeps file support by adding `slackFileParts()` to its message:
+
+```ts
+import { slackFileParts } from "@trigger.dev/slack";
+
+inbound: (event) => ({
+  message: {
+    id: event.event?.ts ?? "",
+    role: "user",
+    parts: [{ type: "text", text: event.event?.text ?? "" }, ...slackFileParts(event.event?.files)],
+  },
+}),
+```
+
+The download happens in the `streamText` passed to `run()`. A `streamText` imported from `ai` sends the Slack URL to the model as is, which the model can't open.
+
+## Answering into the session from elsewhere
+
+The first Slack message binds the session to its thread and to the user it is answering. A [`chat.event`](/webhooks/session-routing#answering-into-a-channel) action that returns `chat.turn()`, or a browser client on the same session, answers into that Slack thread with the same status, streaming and approval buttons.
+
+## Slash commands
+
+Slack posts a slash command as a form, which reaches subscribers as an object of its fields, and the endpoint acknowledges it with an empty `200` so Slack shows the user nothing until you reply. Give slash commands their own endpoint, typed with `SlackSlashCommand`, and set its URL as the command's Request URL under Slash Commands in the Slack app's settings. Use the same Signing Secret as the agent's endpoint. Reply through the command's `response_url`:
+
+```ts /trigger/commands.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+import { webhookSource, type SlackSlashCommand } from "@trigger.dev/slack";
+
+const slackCommands = webhooks.endpoint.define({
+  id: "slack-commands",
+  source: webhookSource<SlackSlashCommand>(),
+});
+
+export const deployCommand = webhook({
+  id: "deploy-command",
+  endpoint: slackCommands,
+  filter: "event.command == '/deploy'",
+  onEvent: async ({ event }) => {
+    await fetch(event.response_url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ response_type: "ephemeral", text: `Deploying ${event.text}` }),
+    });
+  },
+});
+```
+
+Any subscriber works here: a [`chat.event`](/webhooks/session-routing) keyed on `{event.channel_id}:{event.user_id}` routes a user's commands to one session, and a [waiter](/webhooks/waiters) can match on `event.command`.
+
+## Block Kit replies
+
+Replies are sent as markdown. For a reply that is posted rather than streamed (`delivery: "final"`), return `blocks` from `outbound` to post Block Kit. `toSlackBlocks()` splits markdown into `section` blocks under Slack's 3000-character limit, never inside a code fence:
+
+```ts
+import { slack, toSlackBlocks } from "@trigger.dev/slack";
+
+slack({
+  id: "slack",
+  endpoint: slackEvents,
+  token,
+  startOn: appMentions(),
+  delivery: "final",
+  outbound: (reply) =>
+    reply.text
+      ? {
+          text: reply.text.slice(0, 3000), // notification fallback
+          blocks: [{ type: "header", text: { type: "plain_text", text: "Support" } }, ...toSlackBlocks(reply.text)],
+        }
+      : null,
+});
+```
+
+## Options
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Connector id, unique per agent. |
+| `endpoint` | endpoint | The Slack endpoint, declared with `webhooks.endpoint.define({ id, source: webhookSource() })`. `webhook()` tasks can subscribe to the same endpoint. |
+| `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` | `"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

@@ -0,0 +1,250 @@
+---
+title: "Sources and verification"
+description: "Choose an endpoint's source, configure verification, and type the event its subscribers receive."
+sidebarTitle: "Sources & verification"
+---
+
+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
+
+Presets supply the verification configuration, and most also carry the provider's part of the endpoint's [setup prompt](/webhooks/connect#set-it-up-with-an-ai-agent). Set the endpoint's signing secret or public key as described in [Connect a provider](/webhooks/connect).
+
+<CodeGroup>
+
+```ts /trigger/stripe.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const stripe = webhooks.endpoint.define({ id: "stripe", source: webhooks.stripe() });
+
+export const stripeEvents = webhook({
+  id: "stripe-events",
+  endpoint: stripe,
+  onEvent: async ({ event }) => {
+    if (event.type === "payment_intent.succeeded") {
+      console.log(event.id);
+    }
+  },
+});
+```
+
+```ts /trigger/github.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const github = webhooks.endpoint.define({ id: "github", source: webhooks.github() });
+
+export const githubEvents = webhook({
+  id: "github-events",
+  endpoint: github,
+  onEvent: async ({ headers }) => {
+    // GitHub puts the event type in a header
+    console.log(headers.get("x-github-event"));
+  },
+});
+```
+
+```ts /trigger/svix.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const svix = webhooks.endpoint.define({ id: "svix", source: webhooks.svix() });
+
+export const svixEvents = webhook({
+  id: "svix-events",
+  endpoint: svix,
+  onEvent: async ({ event }) => {
+    console.log(event);
+  },
+});
+```
+
+```ts /trigger/composio.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const composio = webhooks.endpoint.define({ id: "composio", source: webhooks.standardWebhooks() });
+
+export const composioEvents = webhook({
+  id: "composio-events",
+  endpoint: composio,
+  onEvent: async ({ event }) => {
+    console.log(event);
+  },
+});
+```
+
+</CodeGroup>
+
+The available presets are `stripe()`, `github()`, `svix()`, `standardWebhooks()`, `square()`, and `discord()`.
+
+### Svix and Standard Webhooks
+
+`svix()` and `standardWebhooks()` use HMAC-SHA256 over `id.timestamp.body` with a base64-encoded `whsec_` secret. Their header names differ:
+
+| Source | Headers |
+| --- | --- |
+| `svix()` | `svix-id`, `svix-timestamp`, `svix-signature` |
+| `standardWebhooks()` | `webhook-id`, `webhook-timestamp`, `webhook-signature` |
+
+Named sources such as `webhooks.clerk()` and `webhooks.composio()` select the corresponding configuration.
+
+## Named providers
+
+Each function below returns a source with its provider's verification configuration. Call it through `webhooks`, for example `webhooks.calCom()`.
+
+| Verification | Source functions |
+| --- | --- |
+| 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()` |
+| 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.
+
+`discord()` answers a verified `{ type: 0 }` PING with HTTP `204` and no body. It also returns `204` for accepted events and `401` for invalid signatures. Set the Discord application's public key as the endpoint's verification credential.
+
+Slack's `url_verification` challenge is handled the same way by `@trigger.dev/slack`.
+
+`whatsapp()` answers Meta's GET verification request when `hub.mode` is `subscribe` and `hub.verify_token` matches the endpoint's verify token. It returns `hub.challenge` as text. The verify token is separate from the App Secret used to verify event signatures; see [Verify a WhatsApp endpoint URL](/webhooks/connect#verify-a-whatsapp-endpoint-url). Endpoints without GET verification return `405` to GET requests.
+
+## Custom providers
+
+`webhooks.custom()` accepts a verification configuration. This source verifies an HMAC-SHA256 signature over the raw body in `x-webhook-signature` and uses the event's `id` for deduplication:
+
+```ts /trigger/internal.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const internal = webhooks.endpoint.define({
+  id: "internal",
+  source: webhooks.custom<{ id: string; message: string }>(
+    {
+      scheme: "hmac",
+      algorithm: "sha256",
+      encoding: "hex",
+      signatureHeader: "x-webhook-signature",
+      signingString: "raw",
+      idempotencyField: { from: "body", name: "id" },
+    },
+    { setupPrompt: "Add the URL under Settings > Webhooks in the admin app and paste the secret there." }
+  ),
+});
+
+export const internalEvents = webhook({
+  id: "internal-events",
+  endpoint: internal,
+  onEvent: async ({ event }) => {
+    console.log(event.message);
+  },
+});
+```
+
+The optional `setupPrompt` is the provider-specific part of the endpoint's [setup prompt](/webhooks/connect#set-it-up-with-an-ai-agent): where the provider's webhook settings are and how to register a URL there. Trigger.dev adds the URL, the subscribers' filters and the signing secret steps around it.
+
+### Form-encoded bodies
+
+A verified body sent as `application/x-www-form-urlencoded` reaches subscribers as an object of its fields, so filters, `chat.event` keys and waiter `match` paths read form fields the way they read JSON fields. A repeated field becomes an array of its values. Slack slash commands and other providers that post forms work this way.
+
+By default an accepted request gets a `200` with a small JSON receipt. Some providers show the response body to the user who triggered the request, so pass `response: { acceptedBody: "empty" }` to answer with an empty `200` instead:
+
+```ts /trigger/forms.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const forms = webhooks.endpoint.define({
+  id: "forms",
+  source: webhooks.custom<{ command: string; text: string; user_id: string }>(
+    { scheme: "url-secret", placement: "query", paramName: "token" },
+    { response: { acceptedBody: "empty" } }
+  ),
+});
+
+export const commands = webhook({
+  id: "commands",
+  endpoint: forms,
+  filter: "event.command == '/deploy'",
+  onEvent: async ({ event }) => {
+    console.log(event.user_id, event.text);
+  },
+});
+```
+
+## Typing the event
+
+Stripe and GitHub sources provide default event shapes; other sources default to `unknown`. Pass an event type to the source function for typed handler parameters and autocomplete. This example uses `Stripe.Event` from the `stripe` package, which must be installed in your project:
+
+```ts /trigger/stripe.ts
+import type Stripe from "stripe";
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const stripe = webhooks.endpoint.define({ id: "stripe", source: webhooks.stripe<Stripe.Event>() });
+
+export const stripeEvents = webhook({
+  id: "stripe-events",
+  endpoint: stripe,
+  onEvent: async ({ event }) => {
+    console.log(event.type, event.id);
+  },
+});
+```
+
+For `webhooks.custom<T>()`, pass your own event type as `T`. The endpoint's event type flows to every subscriber: `webhook()` handlers, `chat.event` keys and filters, and [waiter](/webhooks/waiters) `match` paths are all checked against it.
+
+<Note>
+  Event types are compile-time annotations. Signature verification doesn't validate the body against
+  a TypeScript type. Validate `event` inside `onEvent` if your handler needs runtime schema checks.
+</Note>
+
+## Verification schemes
+
+Requests must pass verification before they reach any subscriber. Sources can check a signature or credential, enforce a timestamp tolerance, and derive an idempotency key for [deduplication](/webhooks/deliveries#deduplication). Verification failures return the source's rejected HTTP status (`400` by default).
+
+Custom sources support these schemes:
+
+| Scheme | Verification |
+| --- | --- |
+| `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. |
+
+<Warning>
+  Query parameters can appear in access logs, proxies, and traces. Prefer a header-based scheme when
+  the provider supports one.
+</Warning>