@trigger.dev/sdk 4.8.5 → 4.8.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (193) hide show
  1. package/dist/commonjs/v3/ai.d.ts +34 -8
  2. package/dist/commonjs/v3/ai.js +304 -168
  3. package/dist/commonjs/v3/ai.js.map +1 -1
  4. package/dist/commonjs/v3/auth.d.ts +4 -4
  5. package/dist/commonjs/v3/auth.js +21 -75
  6. package/dist/commonjs/v3/auth.js.map +1 -1
  7. package/dist/commonjs/v3/chat-client.d.ts +1 -1
  8. package/dist/commonjs/v3/chat.d.ts +1 -1
  9. package/dist/commonjs/v3/prompt.js +6 -8
  10. package/dist/commonjs/v3/prompt.js.map +1 -1
  11. package/dist/commonjs/v3/runs.d.ts +5 -1
  12. package/dist/commonjs/v3/runs.js.map +1 -1
  13. package/dist/commonjs/v3/sessions.js +10 -7
  14. package/dist/commonjs/v3/sessions.js.map +1 -1
  15. package/dist/commonjs/v3/shared.d.ts +2 -2
  16. package/dist/commonjs/v3/shared.js +16 -15
  17. package/dist/commonjs/v3/shared.js.map +1 -1
  18. package/dist/commonjs/v3/steeringContext.d.ts +35 -10
  19. package/dist/commonjs/v3/steeringContext.js +86 -14
  20. package/dist/commonjs/v3/steeringContext.js.map +1 -1
  21. package/dist/commonjs/v3/streams.js +10 -8
  22. package/dist/commonjs/v3/streams.js.map +1 -1
  23. package/dist/commonjs/v3/tasks.d.ts +2 -2
  24. package/dist/commonjs/v3/tasks.js.map +1 -1
  25. package/dist/commonjs/v3/test/mock-chat-agent.js +24 -13
  26. package/dist/commonjs/v3/test/mock-chat-agent.js.map +1 -1
  27. package/dist/commonjs/v3/toolOutputJson.d.ts +17 -0
  28. package/dist/commonjs/v3/toolOutputJson.js +241 -0
  29. package/dist/commonjs/v3/toolOutputJson.js.map +1 -0
  30. package/dist/commonjs/v3/webhooks.d.ts +8 -2
  31. package/dist/commonjs/v3/webhooks.js +20 -11
  32. package/dist/commonjs/v3/webhooks.js.map +1 -1
  33. package/dist/commonjs/version.js +1 -1
  34. package/dist/esm/v3/ai.d.ts +34 -8
  35. package/dist/esm/v3/ai.js +306 -171
  36. package/dist/esm/v3/ai.js.map +1 -1
  37. package/dist/esm/v3/auth.d.ts +4 -4
  38. package/dist/esm/v3/auth.js +22 -76
  39. package/dist/esm/v3/auth.js.map +1 -1
  40. package/dist/esm/v3/chat-client.d.ts +1 -1
  41. package/dist/esm/v3/chat.d.ts +1 -1
  42. package/dist/esm/v3/prompt.js +6 -8
  43. package/dist/esm/v3/prompt.js.map +1 -1
  44. package/dist/esm/v3/runs.d.ts +5 -1
  45. package/dist/esm/v3/runs.js.map +1 -1
  46. package/dist/esm/v3/sessions.js +10 -7
  47. package/dist/esm/v3/sessions.js.map +1 -1
  48. package/dist/esm/v3/shared.d.ts +2 -2
  49. package/dist/esm/v3/shared.js +16 -15
  50. package/dist/esm/v3/shared.js.map +1 -1
  51. package/dist/esm/v3/steeringContext.d.ts +35 -10
  52. package/dist/esm/v3/steeringContext.js +85 -14
  53. package/dist/esm/v3/steeringContext.js.map +1 -1
  54. package/dist/esm/v3/streams.js +10 -8
  55. package/dist/esm/v3/streams.js.map +1 -1
  56. package/dist/esm/v3/tasks.d.ts +2 -2
  57. package/dist/esm/v3/tasks.js.map +1 -1
  58. package/dist/esm/v3/test/mock-chat-agent.js +25 -14
  59. package/dist/esm/v3/test/mock-chat-agent.js.map +1 -1
  60. package/dist/esm/v3/toolOutputJson.d.ts +17 -0
  61. package/dist/esm/v3/toolOutputJson.js +238 -0
  62. package/dist/esm/v3/toolOutputJson.js.map +1 -0
  63. package/dist/esm/v3/webhooks.d.ts +8 -2
  64. package/dist/esm/v3/webhooks.js +20 -11
  65. package/dist/esm/v3/webhooks.js.map +1 -1
  66. package/dist/esm/version.js +1 -1
  67. package/docs/ai/observability.mdx +25 -19
  68. package/docs/ai/prompts.mdx +25 -19
  69. package/docs/ai-chat/actions.mdx +1 -1
  70. package/docs/ai-chat/anatomy.mdx +1 -1
  71. package/docs/ai-chat/backend.mdx +24 -24
  72. package/docs/ai-chat/background-injection.mdx +5 -5
  73. package/docs/ai-chat/chat-local.mdx +2 -2
  74. package/docs/ai-chat/compaction.mdx +47 -18
  75. package/docs/ai-chat/custom-agents.mdx +4 -4
  76. package/docs/ai-chat/error-handling.mdx +4 -4
  77. package/docs/ai-chat/fast-starts.mdx +8 -7
  78. package/docs/ai-chat/frontend.mdx +6 -2
  79. package/docs/ai-chat/lifecycle-hooks.mdx +11 -11
  80. package/docs/ai-chat/migrating-from-a-route-handler.mdx +4 -4
  81. package/docs/ai-chat/migrating-from-hydrate-messages.mdx +1 -1
  82. package/docs/ai-chat/overview.mdx +1 -1
  83. package/docs/ai-chat/patterns/branching-conversations.mdx +1 -1
  84. package/docs/ai-chat/patterns/database-persistence.mdx +2 -2
  85. package/docs/ai-chat/patterns/human-in-the-loop.mdx +1 -1
  86. package/docs/ai-chat/patterns/native-compaction.mdx +29 -9
  87. package/docs/ai-chat/patterns/persistence-and-replay.mdx +1 -1
  88. package/docs/ai-chat/patterns/redacting-telemetry.mdx +2 -2
  89. package/docs/ai-chat/patterns/skills.mdx +2 -2
  90. package/docs/ai-chat/patterns/sub-agents.mdx +1 -1
  91. package/docs/ai-chat/patterns/tool-result-auditing.mdx +1 -1
  92. package/docs/ai-chat/patterns/trusted-edge-signals.mdx +2 -2
  93. package/docs/ai-chat/patterns/version-upgrades.mdx +2 -2
  94. package/docs/ai-chat/pending-messages.mdx +5 -5
  95. package/docs/ai-chat/prompt-caching.mdx +7 -7
  96. package/docs/ai-chat/quick-start.mdx +2 -2
  97. package/docs/ai-chat/testing.mdx +9 -9
  98. package/docs/ai-chat/tools.mdx +9 -5
  99. package/docs/ai-chat/transcript-storage.mdx +2 -2
  100. package/docs/ai-chat/types.mdx +10 -3
  101. package/docs/apikeys.mdx +2 -1
  102. package/docs/cli-login-commands.mdx +12 -0
  103. package/docs/concurrency.mdx +40 -0
  104. package/docs/database-connections.mdx +1 -1
  105. package/docs/deploy-environment-variables.mdx +84 -2
  106. package/docs/deployment/trusted-publishing.mdx +4 -0
  107. package/docs/errors-retrying.mdx +25 -18
  108. package/docs/github-actions.mdx +1 -1
  109. package/docs/github-integration.mdx +32 -1
  110. package/docs/how-it-works.mdx +4 -2
  111. package/docs/introduction.mdx +1 -1
  112. package/docs/mcp-introduction.mdx +7 -1
  113. package/docs/mcp-remote.mdx +90 -0
  114. package/docs/oidc/azure.mdx +81 -0
  115. package/docs/oidc/databricks.mdx +99 -0
  116. package/docs/oidc/doppler.mdx +60 -0
  117. package/docs/oidc/gcp.mdx +109 -0
  118. package/docs/oidc/hugging-face.mdx +90 -0
  119. package/docs/oidc/openrouter.mdx +91 -0
  120. package/docs/oidc/snowflake.mdx +91 -0
  121. package/docs/oidc/vault.mdx +71 -0
  122. package/docs/oidc.mdx +2 -0
  123. package/docs/runs/metadata.mdx +1 -1
  124. package/docs/self-hosting/docker.mdx +2 -0
  125. package/docs/self-hosting/env/webapp.mdx +4 -1
  126. package/docs/self-hosting/kubernetes.mdx +2 -0
  127. package/docs/tasks/schemaTask.mdx +26 -13
  128. package/docs/tasks/streams.mdx +2 -2
  129. package/docs/troubleshooting.mdx +7 -0
  130. package/docs/webhooks/channels.mdx +6 -6
  131. package/docs/webhooks/connect.mdx +9 -75
  132. package/docs/webhooks/custom-providers.mdx +87 -0
  133. package/docs/webhooks/deliveries.mdx +7 -7
  134. package/docs/webhooks/filters.mdx +2 -2
  135. package/docs/webhooks/how-it-works.mdx +58 -0
  136. package/docs/webhooks/human-in-the-loop.mdx +3 -3
  137. package/docs/webhooks/linear.mdx +5 -3
  138. package/docs/webhooks/overview.mdx +20 -71
  139. package/docs/webhooks/own-handler.mdx +62 -0
  140. package/docs/webhooks/pricing-and-limits.mdx +13 -0
  141. package/docs/webhooks/providers/attio.mdx +38 -0
  142. package/docs/webhooks/providers/autumn.mdx +40 -0
  143. package/docs/webhooks/providers/cal-com.mdx +41 -0
  144. package/docs/webhooks/providers/calendly.mdx +41 -0
  145. package/docs/webhooks/providers/clerk.mdx +40 -0
  146. package/docs/webhooks/providers/discord.mdx +45 -0
  147. package/docs/webhooks/providers/docusign.mdx +41 -0
  148. package/docs/webhooks/providers/elevenlabs.mdx +41 -0
  149. package/docs/webhooks/providers/firecrawl.mdx +54 -0
  150. package/docs/webhooks/providers/github.mdx +46 -0
  151. package/docs/webhooks/providers/gitlab.mdx +41 -0
  152. package/docs/webhooks/providers/granola.mdx +44 -0
  153. package/docs/webhooks/providers/hookdeck.mdx +98 -0
  154. package/docs/webhooks/providers/infisical.mdx +41 -0
  155. package/docs/webhooks/providers/jira.mdx +41 -0
  156. package/docs/webhooks/providers/langfuse.mdx +40 -0
  157. package/docs/webhooks/providers/linear.mdx +45 -0
  158. package/docs/webhooks/providers/loops.mdx +40 -0
  159. package/docs/webhooks/providers/metronome.mdx +42 -0
  160. package/docs/webhooks/providers/mux.mdx +40 -0
  161. package/docs/webhooks/providers/openai.mdx +40 -0
  162. package/docs/webhooks/providers/pagerduty.mdx +40 -0
  163. package/docs/webhooks/providers/plain.mdx +41 -0
  164. package/docs/webhooks/providers/planetscale.mdx +40 -0
  165. package/docs/webhooks/providers/recall-ai.mdx +54 -0
  166. package/docs/webhooks/providers/replicate.mdx +41 -0
  167. package/docs/webhooks/providers/resend.mdx +44 -0
  168. package/docs/webhooks/providers/retell.mdx +41 -0
  169. package/docs/webhooks/providers/sentry.mdx +41 -0
  170. package/docs/webhooks/providers/shopify.mdx +49 -0
  171. package/docs/webhooks/providers/slack.mdx +48 -0
  172. package/docs/webhooks/providers/square.mdx +40 -0
  173. package/docs/webhooks/providers/stripe.mdx +86 -0
  174. package/docs/webhooks/providers/supabase.mdx +41 -0
  175. package/docs/webhooks/providers/tailscale.mdx +43 -0
  176. package/docs/webhooks/providers/typeform.mdx +42 -0
  177. package/docs/webhooks/providers/vapi.mdx +47 -0
  178. package/docs/webhooks/providers/vercel.mdx +40 -0
  179. package/docs/webhooks/providers/whatsapp.mdx +45 -0
  180. package/docs/webhooks/providers/workos.mdx +41 -0
  181. package/docs/webhooks/providers/zendesk.mdx +41 -0
  182. package/docs/webhooks/providers.mdx +53 -0
  183. package/docs/webhooks/quick-start.mdx +131 -0
  184. package/docs/webhooks/session-routing.mdx +6 -6
  185. package/docs/webhooks/signing-secrets.mdx +80 -0
  186. package/docs/webhooks/slack.mdx +11 -2
  187. package/docs/webhooks/verification.mdx +139 -0
  188. package/docs/webhooks/waiters.mdx +2 -2
  189. package/docs/webhooks/webhook-tasks.mdx +46 -0
  190. package/package.json +4 -5
  191. package/docs/migrating-from-v3.mdx +0 -332
  192. package/docs/webhooks/public-beta.mdx +0 -70
  193. package/docs/webhooks/sources.mdx +0 -252
@@ -1,10 +1,10 @@
1
1
  ---
2
2
  title: "Channels (chat frontends)"
3
3
  description: "Point Slack (or any chat surface) at an agent: messages become turns and replies post back."
4
- sidebarTitle: "Channels"
4
+ sidebarTitle: "Overview"
5
5
  ---
6
6
 
7
- 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.
7
+ 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** makes the webhook 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 works like the browser chat, with Slack as the frontend.
8
8
 
9
9
  List channels on a [`chat.agent`](/ai-chat/overview) alongside (or instead of) `events`:
10
10
 
@@ -27,11 +27,11 @@ export const supportAgent = chat.agent({
27
27
  }),
28
28
  ],
29
29
  run: async ({ messages, streamText }) =>
30
- streamText({ model: anthropic("claude-sonnet-4-5"), messages }),
30
+ streamText({ model: anthropic("claude-sonnet-5-5"), messages }),
31
31
  });
32
32
  ```
33
33
 
34
- The `run()` loop is unchanged: the agent does not know or care that it is talking to Slack. One verified Slack message in a thread is routed to a durable [session](/ai-chat/sessions) keyed to that thread, run as a turn, and the reply is posted into the thread.
34
+ The `run()` loop is the same as for the browser chat. One verified Slack message in a thread is routed to a durable [session](/ai-chat/sessions) keyed to that thread, run as a turn, and the reply is posted into the thread.
35
35
 
36
36
  ## Slack
37
37
 
@@ -98,7 +98,7 @@ slack({
98
98
 
99
99
  ## Stopping a turn from the channel
100
100
 
101
- A connector can map an event to a control with `onControl`. Returning `{ kind: "stop" }` while a turn is running aborts it through the run's `stopSignal`, exactly like the browser's stop button: the partial reply posts with `stopped: true` and the event is consumed instead of running as a turn. `linear()` and `slack()` map their stop buttons this way; a custom connector might map a `/stop` command:
101
+ A connector can map an event to a control with `onControl`. Returning `{ kind: "stop" }` while a turn is running aborts it through the run's `stopSignal`, as the browser's stop button does: the partial reply posts with `stopped: true` and the event is consumed instead of running as a turn. `linear()` and `slack()` map their stop buttons this way; a custom connector might map a `/stop` command:
102
102
 
103
103
  ```ts
104
104
  chat.channels.custom({
@@ -139,7 +139,7 @@ chat.channels.custom({
139
139
 
140
140
  ## Files, buttons and steering
141
141
 
142
- Three more hooks cover what a chat surface carries besides text:
142
+ These hooks cover what a chat surface carries besides text:
143
143
 
144
144
  - `download(url, { handle })` fetches files only the surface's credentials can read. Have `inbound` return file parts on the surface's URLs, and the `streamText` passed to `run()` asks each connector's `download` for every file URL in the prompt (return null for URLs it doesn't own). Downloads are cached for the run and the transcript keeps the URL. A file `download` throws on becomes a short note in that turn's messages, and the turn still runs.
145
145
  - `toAction(event)` maps a click on a control the agent posted to an action. It reaches `onAction`, validated against `actionSchema`, with the click itself as `channel.event`. Returning `chat.turn(message)` answers in the bound thread. Return null for anything else, such as a click answering a pending tool call, which `onInteraction` handles.
@@ -1,56 +1,13 @@
1
1
  ---
2
2
  title: "Connect a webhook provider"
3
- description: "Register an endpoint's URL and signing secret with the provider, by hand or with an AI coding agent, then check that events arrive."
3
+ description: "Register an endpoint's URL and signing credential with the provider, by hand or with an AI coding agent, then check that events arrive."
4
4
  sidebarTitle: "Connect a provider"
5
5
  ---
6
6
 
7
- 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.
7
+ 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. Each [provider page](/webhooks/providers) shows where that provider keeps its webhook settings; for a provider that isn't listed, define a [custom provider](/webhooks/custom-providers) first.
8
8
 
9
9
  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.
10
10
 
11
- ## Set it up with an AI agent
12
-
13
- Each endpoint has a setup prompt: the URL, the events its subscribers filter on, the provider's own setup steps, and how to generate or store the signing secret. Choose **Copy setup prompt** on the Webhooks page or the endpoint's page, and paste it into an AI coding agent such as Claude Code.
14
-
15
- The prompt tells the agent to use the Trigger.dev MCP server (`npx trigger.dev@latest install-mcp`), which has these tools:
16
-
17
- | Tool | What it does |
18
- | --- | --- |
19
- | `list_webhook_endpoints` | Lists the environment's endpoints, with their URL and whether a secret is set. |
20
- | `get_webhook_endpoint_details` | Reads one endpoint: URL, subscribers and their filters, secret state, and the setup prompt. |
21
- | `generate_webhook_secret` | Generates a signing secret and returns it once, for providers where you choose the secret. Optionally keeps accepting the old secret (`previousSecretTtlSeconds`). |
22
- | `set_webhook_secret` | Stores a secret the provider issued. Optionally keeps accepting the old secret (`previousSecretTtlSeconds`). |
23
-
24
- ### Keep the secret out of the agent's context
25
-
26
- A secret passed to `set_webhook_secret`, or returned by `generate_webhook_secret`, becomes part of the agent's conversation. The [CLI webhooks commands](/cli-webhooks-commands) store the secret without printing it, and the MCP tool descriptions point agents that can run shell commands to them:
27
-
28
- ```bash
29
- # Store a secret the provider issued, from an env file or a pipe
30
- npx trigger.dev@latest webhooks set-secret stripe --env prod --from-env STRIPE_WEBHOOK_SECRET
31
-
32
- # Generate one and save it to .env.local for the agent to pass to the provider by name
33
- npx trigger.dev@latest webhooks generate-secret github --env prod --to-env GITHUB_WEBHOOK_SECRET
34
- ```
35
-
36
- Without the MCP server, the same operations are available on the REST API with the environment's secret key:
37
-
38
- | Request | What it does |
39
- | --- | --- |
40
- | [`GET /api/v1/webhooks/endpoints`](/management/webhooks/list-endpoints) | Lists the environment's endpoints, with their URL and whether a secret is set. |
41
- | [`GET /api/v1/webhooks/endpoints/{endpointId}`](/management/webhooks/retrieve-endpoint) | Reads the endpoint, including `subscribers` and `setupPrompt`. |
42
- | [`POST /api/v1/webhooks/endpoints/{endpointId}/rotate-secret`](/management/webhooks/generate-secret) | Generates a secret and returns it once. |
43
- | [`PUT /api/v1/webhooks/endpoints/{endpointId}/secret`](/management/webhooks/set-secret) | Stores a secret, sent as `{ "secret": "..." }`. |
44
-
45
- `endpointId` is the endpoint's declared id (the `id` passed to `webhooks.endpoint.define`) or its `wh_` id, shown on its page and returned by `list_webhook_endpoints`:
46
-
47
- ```bash
48
- curl -X PUT "https://api.trigger.dev/api/v1/webhooks/endpoints/stripe/secret" \
49
- -H "Authorization: Bearer $TRIGGER_SECRET_KEY" \
50
- -H "Content-Type: application/json" \
51
- -d '{"secret": "whsec_..."}'
52
- ```
53
-
54
11
  ## Set it up by hand
55
12
 
56
13
  <Steps>
@@ -58,13 +15,10 @@ curl -X PUT "https://api.trigger.dev/api/v1/webhooks/endpoints/stripe/secret" \
58
15
  Open the endpoint from the Webhooks page and copy the **Webhook URL**.
59
16
  </Step>
60
17
  <Step title="Configure the provider">
61
- Add the URL as the webhook destination in your provider's dashboard and select the events your subscribers need. The provider's setup determines where the verification credential comes from:
62
-
63
- | Provider setup | Action |
64
- | --- | --- |
65
- | The provider supplies a signing secret, as Stripe and Svix do | Copy the secret from the provider, then choose **Set signing secret** on the endpoint. |
66
- | The provider accepts a secret you choose, as GitHub does | Choose **Generate secret** on the endpoint, then paste the value into the provider's webhook configuration. |
67
- | The provider uses an asymmetric signature, as Discord does | Copy the application's public key from the provider and choose **Set public key** on the endpoint. |
18
+ Add the URL as the webhook destination in your provider's dashboard and select the events your subscribers need.
19
+ </Step>
20
+ <Step title="Set the credential">
21
+ Choose **Set signing secret** and paste the secret the provider issues, choose **Generate secret** and paste the value into the provider, or choose **Set public key** for a provider that signs with a key pair. The [provider page](/webhooks/providers) says which one it needs; see [Signing secrets](/webhooks/signing-secrets#set-the-credential).
68
22
 
69
23
  Set the credential before sending a test event or asking the provider to validate the URL.
70
24
  </Step>
@@ -76,28 +30,8 @@ Send a test event from your provider, or use the endpoint's **Test** tab. The ev
76
30
 
77
31
  If no delivery appears, check that the provider uses the copied URL and that both sides have the same signing secret or public key.
78
32
 
79
- ## Verify a WhatsApp endpoint URL
80
-
81
- `webhooks.whatsapp()` also needs a verify token for Meta's URL check. On the endpoint, choose **Generate verify token** and paste the value into Meta's **Verify Token** field. Set Meta's App Secret as the signing secret, then validate the URL in Meta's dashboard.
82
-
83
- The verify token answers the URL check. The signing secret verifies event deliveries. See [Sources and verification](/webhooks/sources#endpoint-validation) for the response behavior.
84
-
85
- ## Rotate a credential
86
-
87
- Choose **Rotate signing secret** to replace a provider-supplied secret. For a secret you generate, choose **Regenerate secret**, copy the new value, and update the provider's configuration. Use **Rotate public key** when replacing an asymmetric provider's key.
88
-
89
- Both dialogs ask how long to keep accepting the old secret: **Stop immediately**, 1 hour, 24 hours (the default) or 7 days. Until then, deliveries signed with either secret verify, so you can update the provider without failing any. Choose **Stop immediately** if the old secret leaked.
90
-
91
- Through the MCP tools or the REST API, pass `previousSecretTtlSeconds` (at most 604800, 7 days). The response's `previousSecretExpiresAt` says when the old secret stops working. Without it, the old secret stops working straight away:
33
+ ## Set it up with an AI agent
92
34
 
93
- ```bash
94
- curl -X POST "https://api.trigger.dev/api/v1/webhooks/endpoints/github/rotate-secret" \
95
- -H "Authorization: Bearer $TRIGGER_SECRET_KEY" \
96
- -H "Content-Type: application/json" \
97
- -d '{"previousSecretTtlSeconds": 3600}'
98
- ```
35
+ Each endpoint has a setup prompt: the URL, the events its subscribers filter on, the provider's own setup steps, and how to generate or store the signing secret. Choose **Copy setup prompt** on the Webhooks page or the endpoint's page, and paste it into an AI coding agent such as Claude Code.
99
36
 
100
- <Warning>
101
- Trigger.dev stores credentials encrypted and doesn't display saved values. Copy a generated secret
102
- before closing the dialog.
103
- </Warning>
37
+ The prompt tells the agent to use the Trigger.dev MCP server (`npx trigger.dev@latest install-mcp`), which reads the endpoint and stores or generates its secret. See [Signing secrets](/webhooks/signing-secrets) for the MCP tools, CLI commands and REST API.
@@ -0,0 +1,87 @@
1
+ ---
2
+ title: "Custom webhook providers"
3
+ sidebarTitle: "Custom providers"
4
+ description: "Verify webhooks from a provider that isn't built in by passing your own HMAC, shared-secret, URL-secret or public-key configuration to webhooks.custom()."
5
+ ---
6
+
7
+ **`webhooks.custom()` verifies any provider that signs or authenticates its webhooks with one of four supported schemes.** Use it when the provider isn't in the [built-in providers](/webhooks/providers). Subscribers, filters, deliveries and the [setup prompt](/webhooks/connect#set-it-up-with-an-ai-agent) work the same as with a built-in provider.
8
+
9
+ ## Define a custom provider
10
+
11
+ Pass the verification configuration to `webhooks.custom()`. This source verifies an HMAC-SHA256 signature over the raw body in `x-webhook-signature` and uses the event's `id` for deduplication:
12
+
13
+ ```ts /trigger/internal.ts
14
+ import { webhook, webhooks } from "@trigger.dev/sdk";
15
+
16
+ export const internal = webhooks.endpoint.define({
17
+ id: "internal",
18
+ source: webhooks.custom<{ id: string; message: string }>(
19
+ {
20
+ scheme: "hmac",
21
+ algorithm: "sha256",
22
+ encoding: "hex",
23
+ signatureHeader: "x-webhook-signature",
24
+ signingString: "raw",
25
+ idempotencyField: { from: "body", name: "id" },
26
+ },
27
+ { setupPrompt: "Add the URL under Settings > Webhooks in the admin app and paste the secret there." }
28
+ ),
29
+ });
30
+
31
+ export const internalEvents = webhook({
32
+ id: "internal-events",
33
+ endpoint: internal,
34
+ onEvent: async ({ event }) => {
35
+ console.log(event.message);
36
+ },
37
+ });
38
+ ```
39
+
40
+ To accept a signature from more than one header, list the extra headers in `additionalSignatureHeaders` (up to 4). Trigger.dev parses each one like `signatureHeader` and accepts a match in any of them. Use this when a provider sends a second signature, for example one signed with the previous secret during a rotation. `signatureHeader` is still required. The built-in [`hookdeck()`](/webhooks/providers/hookdeck) source already checks `X-Hookdeck-Signature-2` this way.
41
+
42
+ 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.
43
+
44
+ ## Form-encoded bodies
45
+
46
+ 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.
47
+
48
+ 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:
49
+
50
+ ```ts /trigger/forms.ts
51
+ import { webhook, webhooks } from "@trigger.dev/sdk";
52
+
53
+ export const forms = webhooks.endpoint.define({
54
+ id: "forms",
55
+ source: webhooks.custom<{ command: string; text: string; user_id: string }>(
56
+ { scheme: "url-secret", placement: "query", paramName: "token" },
57
+ { response: { acceptedBody: "empty" } }
58
+ ),
59
+ });
60
+
61
+ export const commands = webhook({
62
+ id: "commands",
63
+ endpoint: forms,
64
+ filter: "event.command == '/deploy'",
65
+ onEvent: async ({ event }) => {
66
+ console.log(event.user_id, event.text);
67
+ },
68
+ });
69
+ ```
70
+
71
+
72
+
73
+ ## Verification schemes
74
+
75
+ `webhooks.custom()` supports these schemes:
76
+
77
+ | Scheme | Verification |
78
+ | --- | --- |
79
+ | `hmac` | Computes an HMAC over the raw body or a signing template and compares it with a request header. |
80
+ | `shared-secret` | Compares a static token supplied in a header, bearer token, basic authentication, or request body. |
81
+ | `url-secret` | Compares a token in a URL query parameter. Hosted endpoints don't support path placement. |
82
+ | `asymmetric` | Verifies an Ed25519, ECDSA (P-256 with SHA-256, P-384 with SHA-384), or RSA-SHA256 signature using the provider's public key. Set `prehash: "sha256"` when the provider signs a SHA-256 digest of the signing string instead of the string itself. |
83
+
84
+ <Warning>
85
+ Query parameters can appear in access logs, proxies, and traces. Prefer a header-based scheme when
86
+ the provider supports one.
87
+ </Warning>
@@ -58,7 +58,7 @@ curl -X POST "https://api.trigger.dev/api/v1/webhooks/deliveries/whd_1234/replay
58
58
  -H "Authorization: Bearer $TRIGGER_SECRET_KEY"
59
59
  ```
60
60
 
61
- Add `?targetId=` to send it to one subscriber regardless of its filter. `targetId` is the subscriber id: a `webhook()` task's id, or `agentId:eventId` for an agent's `chat.event` or channel. A replay never resumes waiting runs.
61
+ Add `?targetId=` to send it to one subscriber regardless of its filter. `targetId` is the subscriber id: a `webhook()` task's id, `agentId:eventId` for an agent's `chat.event`, or `agentId:connectorId` for a channel. A replay never resumes waiting runs.
62
62
 
63
63
  ## From an agent or the API
64
64
 
@@ -81,20 +81,20 @@ Trigger.dev uses the endpoint and idempotency key to deduplicate incoming events
81
81
  | What is deduplicated | Window |
82
82
  | --- | --- |
83
83
  | Delivery records | Six hours by default. |
84
- | Task runs | Three days for Stripe; one day for other sources. |
84
+ | Task runs | Three days for Stripe; one day for other providers. |
85
85
 
86
86
  A retry after the delivery window expires can create another delivery record. If the task-run idempotency window is still active, routing returns the existing run instead of starting another one.
87
87
 
88
88
  When the source maps a provider event ID, that ID becomes the key, so the provider's own retries of an event are recognised as duplicates:
89
89
 
90
- | Key | Sources |
90
+ | Key | Providers |
91
91
  | --- | --- |
92
- | A header | GitHub (`X-GitHub-Delivery`), Svix and Autumn (`svix-id`), Standard Webhooks, Loops and Granola (`webhook-id`), Linear (`Linear-Delivery`), PagerDuty (`X-Webhook-Id`), Jira (`X-Atlassian-Webhook-Identifier`), Zendesk (`X-Zendesk-Webhook-Invocation-Id`), Attio (`Idempotency-Key`), Shopify (`X-Shopify-Webhook-Id`), Hookdeck (`X-Hookdeck-Eventid`, or `<prefix>-eventid` with a custom header prefix) |
93
- | A body field | Stripe, Notion, Vercel, Intercom, WorkOS, Metronome, Mux, Langfuse and Plain (`id`), Square, Slack and Typeform (`event_id`), Firecrawl (`webhookId`) |
92
+ | A header | GitHub (`X-GitHub-Delivery`); Svix, Clerk, Resend and Autumn (`svix-id`); Standard Webhooks, OpenAI, Replicate, Recall.ai, Loops and Granola (`webhook-id`); Linear (`Linear-Delivery`); PagerDuty (`X-Webhook-Id`); Jira (`X-Atlassian-Webhook-Identifier`); Zendesk (`X-Zendesk-Webhook-Invocation-Id`); Attio (`Idempotency-Key`); Shopify (`X-Shopify-Webhook-Id`); Hookdeck (`X-Hookdeck-Eventid`, or `<prefix>-eventid` with a custom header prefix) |
93
+ | A body field | Stripe, Vercel, WorkOS, Metronome, Mux, Langfuse and Plain (`id`); Square, Slack and Typeform (`event_id`); Firecrawl (`webhookId`) |
94
94
 
95
- The other named sources (Zoom, Calendly, Sentry, DocuSign, ElevenLabs, Vapi, Retell, Tailscale, Infisical, PlanetScale, Supabase, Discord) use the fallback below.
95
+ The other built-in providers (Calendly, Cal.com, Sentry, DocuSign, ElevenLabs, Vapi, Retell, Tailscale, Infisical, PlanetScale, Supabase, Discord, GitLab and WhatsApp) use the fallback below.
96
96
 
97
- If the source doesn't map an event ID, the key is derived from the raw body, timestamp, and signature. A retry with a different timestamp or signature can therefore produce a different key. For a [custom source](/webhooks/sources#custom-providers), set `idempotencyField` to a stable event identifier when the provider supplies one.
97
+ If the source doesn't map an event ID, the key is derived from the raw body, timestamp, and signature. A retry with a different timestamp or signature can therefore produce a different key. For a [custom provider](/webhooks/custom-providers), set `idempotencyField` to a stable event identifier when the provider supplies one.
98
98
 
99
99
  ## Verification and recording
100
100
 
@@ -27,7 +27,7 @@ export const largePayments = webhook({
27
27
 
28
28
  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`.
29
29
 
30
- 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.
30
+ The filter is checked against the [endpoint's event type](/webhooks/verification#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.
31
31
 
32
32
  ## Narrow a union event
33
33
 
@@ -77,7 +77,7 @@ A path reads from one of three namespaces:
77
77
 
78
78
  - `event.*`: the verified, parsed request body, for example `event.data.object.amount`.
79
79
  - `header.*`: an inbound request header, matched case-insensitively, for example `header.x-github-event`.
80
- - `webhook.*`: endpoint and delivery metadata: `source`, `id`, `deliveryId`, `externalRef`, and `tenantId`. The last two depend on the endpoint configuration.
80
+ - `webhook.*`: endpoint and delivery metadata: `source`, `id`, `deliveryId`, `externalRef`, and `tenantId`. The last two depend on the endpoint configuration. `deliveryId` is the provider's event ID, or a hash of the request when the provider sends none; it isn't the `whd_` delivery id.
81
81
 
82
82
  Paths must have non-empty segments. `event.data.amount` is valid; `event.`, `event..amount`, and `event.amount.` are rejected.
83
83
 
@@ -0,0 +1,58 @@
1
+ ---
2
+ title: "How webhooks work"
3
+ sidebarTitle: "How it works"
4
+ description: "Trigger.dev verifies, deduplicates and stores every webhook before answering the provider, then routes it to tasks, waiting runs and agents."
5
+ ---
6
+
7
+ **Trigger.dev stores every webhook before it answers the provider, then routes it to the tasks, waiting runs and agents subscribed to the endpoint.**
8
+
9
+ A webhook is an HTTP request a provider such as Stripe or GitHub sends to your URL when something happens. Providers expect a fast `2xx` response and retry until they get one, so the same event can arrive more than once. A handler that does slow work before answering, or answers before saving the event, can time out, run twice or lose the event.
10
+
11
+ ## What happens to a request
12
+
13
+ ```mermaid
14
+ sequenceDiagram
15
+ participant P as Provider
16
+ participant T as Trigger.dev
17
+ participant S as Subscribers
18
+ P->>T: POST to the endpoint URL
19
+ Note over T: Verify, deduplicate, store
20
+ T-->>P: 200 OK
21
+ T->>S: Start runs, resume waiting runs, message agents
22
+ ```
23
+
24
+ 1. **Verify.** The endpoint checks the provider's signature or secret with the endpoint's [credential](/webhooks/signing-secrets). A request that fails is rejected and never reaches a subscriber. Provider handshakes, such as Slack's URL check, are answered here and create no delivery.
25
+ 2. **Deduplicate.** A retry of an event that already arrived is answered as a duplicate. Most [built-in providers](/webhooks/providers) dedupe on the provider's event ID.
26
+ 3. **Store, then answer.** The delivery is durably stored before the provider gets its `200`. Once the provider has its answer it stops retrying, and Trigger.dev is responsible for the event from then on.
27
+ 4. **Route.** Each subscriber's [filter](/webhooks/filters) is checked. Matching tasks start a run, matching [waiters](/webhooks/waiters) resume their paused runs, and agent sessions receive the event as a message.
28
+
29
+ Each endpoint and environment has a rate limit. Over it, the endpoint answers `429` with `Retry-After`, so the provider sends the event again later instead of dropping it. See [Limits](/limits#webhook-ingest-rate-limits).
30
+
31
+ ## Endpoints are declared in code
32
+
33
+ You declare an endpoint next to your tasks with `webhooks.endpoint.define()`. When you run `trigger dev` or deploy, the CLI sends the endpoints it finds to Trigger.dev, and the environment is synced to match: new endpoints are created, and removed ones are deactivated but keep their URL and secret, so adding one back restores it.
34
+
35
+ Each environment gets its own URL for each endpoint. Your dev environment has its own URL too, so you don't need a tunnel for local development. A delivery that arrives while `trigger dev` isn't running waits for it like any other dev run.
36
+
37
+ ## One endpoint, many subscribers
38
+
39
+ A provider account usually needs one URL, so every subscriber shares the endpoint. One delivery can start task runs, resume [waiting runs](/webhooks/waiters) and reach agent sessions at the same time. See [What can subscribe](/webhooks/overview#what-can-subscribe).
40
+
41
+ A delivery that no filter matches is recorded as `FILTERED` and starts no run, so it costs nothing. See [Pricing and limits](/webhooks/pricing-and-limits).
42
+
43
+ ## Retries and duplicates
44
+
45
+ Duplicates are caught in two places:
46
+
47
+ - **When the webhook arrives.** A retry with the same event ID is answered as a duplicate and isn't stored again.
48
+ - **When the run starts.** Each delivery triggers its task with an [idempotency key](/idempotency) built from the endpoint and the event, kept for the provider's retry window. A retry that gets past the first check finds the existing run instead of starting a second one.
49
+
50
+ A waiter completes once, and an agent session skips an event it has already received. A resend after the retry window, such as resending an event from the provider's dashboard a week later, starts a new run, so keep side effects in your handler idempotent.
51
+
52
+ See [Deduplication](/webhooks/deliveries#deduplication) for the windows and the key each provider uses.
53
+
54
+ ## Every delivery is recorded
55
+
56
+ Each delivery keeps its headers, body and the result for every subscriber, with links to the runs it started. A filtered delivery shows which clause failed and with what value. You can replay a delivery from the dashboard, the REST API or the MCP server. See [Deliveries and endpoints](/webhooks/deliveries).
57
+
58
+ For the design choices and infrastructure behind this, read [How we built webhooks](https://trigger.dev/blog/how-we-built-webhooks).
@@ -1,10 +1,10 @@
1
1
  ---
2
- title: "Human-in-the-loop"
2
+ title: "Human-in-the-loop over a channel"
3
3
  sidebarTitle: "Human-in-the-loop"
4
4
  description: "Pause an agent mid-turn to get a human decision from the channel (Slack approve/deny), then resume with the answer."
5
5
  ---
6
6
 
7
- **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.
7
+ **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. The click arrives as a webhook on the same endpoint as the conversation's messages, and that delivery resumes the paused run. To pause a run until any other webhook arrives, use a [waiter](/webhooks/waiters). 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 includes Approve and Deny buttons.
8
8
 
9
9
  ## How it works
10
10
 
@@ -67,7 +67,7 @@ export const supportAgent = chat.agent({
67
67
  tools: { requestApproval },
68
68
  run: async ({ messages, tools, streamText }) =>
69
69
  streamText({
70
- model: anthropic("claude-sonnet-4-5"),
70
+ model: anthropic("claude-sonnet-5-5"),
71
71
  messages,
72
72
  tools,
73
73
  system:
@@ -6,6 +6,8 @@ sidebarTitle: "Linear agents"
6
6
 
7
7
  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.
8
8
 
9
+ Linear is one of our deep integrations: as well as delivering [webhook events](/webhooks/providers/linear), the connector handles Linear's agent session UI for you.
10
+
9
11
  ```ts
10
12
  import { webhooks } from "@trigger.dev/sdk";
11
13
  import { chat } from "@trigger.dev/sdk/ai";
@@ -19,7 +21,7 @@ export const triage = chat.agent({
19
21
  channels: [linear({ id: "linear", endpoint: linearEvents, token: process.env.LINEAR_ACCESS_TOKEN! })],
20
22
  tools: { searchDocs, createSubIssues },
21
23
  run: async ({ messages, tools, signal, streamText }) =>
22
- streamText({ model: anthropic("claude-sonnet-4-5"), messages, tools, abortSignal: signal }),
24
+ streamText({ model: anthropic("claude-sonnet-5-5"), messages, tools, abortSignal: signal }),
23
25
  });
24
26
  ```
25
27
 
@@ -46,7 +48,7 @@ The `run()` loop is the same one a browser chat or a Slack thread uses. Verifica
46
48
 
47
49
  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.
48
50
 
49
- A follow-up prompt on the session is just the message. If the user hits **Stop** in Linear, see [Stopping](#stopping).
51
+ A follow-up prompt on the session is the message itself. If the user hits **Stop** in Linear, see [Stopping](#stopping).
50
52
 
51
53
  Images and PDFs uploaded to Linear reach the model as files: screenshots in the prompt, in the comment that mentioned the agent, or in the issue description. The transcript keeps the upload link, and the `streamText` passed to `run()` downloads the file with the app's token when the model reads it, at most ten per message. A file that can't be downloaded reaches the model as a short note. A custom `inbound` keeps this by adding `linearFileParts(markdown)` to its message parts.
52
54
 
@@ -107,7 +109,7 @@ For manual control, `chat.surface<LinearRunSurface>()` returns the current turn'
107
109
 
108
110
  ## Approvals and choices
109
111
 
110
- A tool with no `execute` pauses the turn for a human decision, exactly as on [any channel](/webhooks/human-in-the-loop). On Linear the connector posts an elicitation card with Approve and Deny options. The card lays the tool input out as markdown: a list of proposed items becomes a numbered list with a bold title per item, a flat object becomes key and value bullets, and only shapes it cannot lay out fall back to JSON. For a card written for the tool, pass a renderer per tool name:
112
+ A tool with no `execute` pauses the turn for a human decision, as on [any channel](/webhooks/human-in-the-loop). On Linear the connector posts an elicitation card with Approve and Deny options. The card lays the tool input out as markdown: a list of proposed items becomes a numbered list with a bold title per item, a flat object becomes key and value bullets, and only shapes it cannot lay out fall back to JSON. For a card written for the tool, pass a renderer per tool name:
111
113
 
112
114
  ```ts
113
115
  linear({
@@ -4,7 +4,18 @@ description: "Receive provider webhooks on hosted, verified endpoints and route
4
4
  sidebarTitle: "Overview"
5
5
  ---
6
6
 
7
- **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.
7
+ **A webhook endpoint is one hosted URL that you register with a provider.** Trigger.dev [verifies](/webhooks/verification) every request from the provider, records it as a [delivery](/webhooks/deliveries), and hands the event to everything subscribed to the endpoint.
8
+
9
+ Webhooks can start, resume or message your AI agents.
10
+
11
+ <Note>
12
+ Webhooks are in public beta for every organization, in `@trigger.dev/sdk` 4.8.1 and later. The API
13
+ may change before general availability; we announce changes in the
14
+ [changelog](https://trigger.dev/changelog). Send bugs and feedback to
15
+ [eric@trigger.dev](mailto:eric@trigger.dev) with the delivery id (`whd_...`) or run id.
16
+ </Note>
17
+
18
+ There are more than 40 [built-in providers](/webhooks/providers), including Stripe, GitHub, Firecrawl and Linear. For any other provider, define a [custom provider](/webhooks/custom-providers). If you prefer to handle webhooks in your own app, you can [trigger tasks from your own handler](/webhooks/own-handler). To set one up from scratch, follow the [quick start](/webhooks/quick-start).
8
19
 
9
20
  Declare the endpoint once, then subscribe to it:
10
21
 
@@ -46,78 +57,16 @@ Stripe gets one URL. A checkout event runs `fulfill-order`, a refund runs `recor
46
57
  | Chat frontend | a [channel connector](/webhooks/channels) such as `chat.channels.custom({ endpoint })` | Runs a turn on the conversation's session and posts the reply back. |
47
58
  | Waiting run | [`webhooks.waiter.create(endpoint, { match })`](/webhooks/waiters) | Resumes a run that is waiting for this event. |
48
59
 
49
- Each subscriber has its own [filter](/webhooks/filters), so one delivery can reach several subscribers and skip the rest. An endpoint can have up to 25 subscribers. An endpoint with no subscribers still gets a URL, so you can register it with the provider before writing the handlers.
50
-
51
- ## The handler
52
-
53
- `onEvent` receives:
54
-
55
- | Argument | Value |
56
- | --- | --- |
57
- | `event` | The verified request body, parsed as JSON. Its TypeScript type comes from the [source](/webhooks/sources#typing-the-event). |
58
- | `headers` | Request headers as a Web `Headers` object, with case-insensitive `get()` and `has()` methods. Credentials such as signatures are removed. |
59
- | `endpoint` | The endpoint the delivery arrived on: `id`, `declaredId`, `tenantId`, `externalRef`, and the `metadata` you declared. |
60
- | `ctx` | The same [run context](/context) that regular tasks receive. |
61
-
62
- `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:
63
-
64
- ```ts
65
- export const orders = webhook({
66
- id: "stripe-orders",
67
- endpoint: stripe,
68
- queue: { concurrencyLimit: 1 },
69
- retry: { maxAttempts: 5 },
70
- onEvent: async ({ event }) => {
71
- // ...
72
- },
73
- });
74
- ```
75
-
76
- 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.
77
-
78
- `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.
60
+ Each subscriber has its own [filter](/webhooks/filters), so one delivery can reach several subscribers and skip the rest. An endpoint can have up to 25 tasks, agent sessions and channels subscribed; waiting runs don't count toward that limit. An endpoint with no subscribers still gets a URL, so you can register it with the provider before writing the handlers. See [Webhook tasks](/webhooks/webhook-tasks) for what a handler receives and the options it takes.
79
61
 
80
- ## How it works
81
-
82
- The CLI finds your endpoints and subscribers during `trigger dev` and deployment, and each environment gets one endpoint per declared id. The endpoint holds the URL and the credential used to verify requests.
83
-
84
- 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.
85
-
86
- ## Pricing and limits
87
-
88
- Webhooks have no separate charge on Trigger.dev Cloud. Receiving, verifying, filtering and recording deliveries is included in every plan. The runs a delivery starts or resumes are billed like any other run: a per-run invocation cost plus compute time. See [pricing](https://trigger.dev/pricing).
89
-
90
- A delivery that no subscriber's filter matches starts no run for any subscriber, so it costs nothing. A run already waiting for that webhook still resumes. A run [waiting](/webhooks/waiters) for a webhook is suspended, so it uses no compute until the webhook arrives.
91
-
92
- 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).
93
-
94
- ## Connect it
95
-
96
- 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).
97
-
98
- <CardGroup cols={2}>
99
- <Card title="Connect a provider" icon="plug" href="/webhooks/connect">
100
- Register the URL and signing secret, then send a test event.
101
- </Card>
102
- <Card title="Sources and verification" icon="shield-check" href="/webhooks/sources">
103
- Choose a provider source or define a custom verification scheme.
104
- </Card>
105
- <Card title="Filters" icon="filter" href="/webhooks/filters">
106
- Choose which events reach each subscriber.
107
- </Card>
108
- <Card title="Waiters" icon="hourglass" href="/webhooks/waiters">
109
- Pause a run until a matching webhook arrives.
110
- </Card>
111
- <Card title="Deliveries and endpoints" icon="inbox" href="/webhooks/deliveries">
112
- Inspect received events and where each one went.
113
- </Card>
114
- <Card title="Session routing" icon="arrows-to-dot" href="/webhooks/session-routing">
115
- Route deliveries to a durable per-key agent session.
62
+ <CardGroup cols={3}>
63
+ <Card title="Quick start" icon="rocket" href="/webhooks/quick-start">
64
+ Declare an endpoint and receive your first event.
116
65
  </Card>
117
- <Card title="Channels" icon="comments" href="/webhooks/channels">
118
- Turn a webhook into a chat frontend for an agent.
66
+ <Card title="Providers" icon="list" href="/webhooks/providers">
67
+ Set up more than 40 providers, including Stripe, GitHub and Firecrawl.
119
68
  </Card>
120
- <Card title="Human-in-the-loop" icon="user-check" href="/webhooks/human-in-the-loop">
121
- Approvals and interactive controls over a channel.
69
+ <Card title="How it works" icon="diagram-project" href="/webhooks/how-it-works">
70
+ What happens to a request, from verification to runs.
122
71
  </Card>
123
72
  </CardGroup>
@@ -0,0 +1,62 @@
1
+ ---
2
+ title: "Use your own webhook handler"
3
+ sidebarTitle: "Using your own handler"
4
+ description: "Receive webhooks in a route in your own app and trigger tasks from it with tasks.trigger()."
5
+ ---
6
+
7
+ **Trigger.dev has built-in webhook endpoints, and we recommend them for most projects.** They verify each provider's signature, drop duplicate retries, record every delivery, and route events to tasks, agents and waiting runs. See [Webhooks](/webhooks/overview).
8
+
9
+ If you prefer to handle webhooks yourself, receive them in a route in your own app and trigger runs from there with `tasks.trigger()`, the same way any backend code does.
10
+
11
+ ## When to use your own handler
12
+
13
+ | Use a hosted endpoint | Use your own handler |
14
+ | --- | --- |
15
+ | You want Trigger.dev to verify signatures, deduplicate retries and record deliveries. | You already have a handler in production and only want to move the work into a task. |
16
+ | One event should reach several tasks, agents or waiting runs. | The provider needs a response body that your code computes from the request. |
17
+ | You want to replay deliveries and see which runs each one started. | The request must pass through your app first, for example to look up a tenant before triggering. |
18
+
19
+ ## Trigger a task from your route
20
+
21
+ Verify the request with the provider's SDK, then trigger the task. This Next.js route uses Stripe's SDK; import the task as a type so the route doesn't bundle the task code.
22
+
23
+ ```ts app/api/webhooks/stripe/route.ts
24
+ import Stripe from "stripe";
25
+ import { tasks } from "@trigger.dev/sdk";
26
+ import type { handleStripeEvent } from "@/trigger/handle-stripe-event";
27
+
28
+ const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
29
+
30
+ export async function POST(request: Request) {
31
+ const body = await request.text();
32
+
33
+ // Verify the signature before trusting the body
34
+ const event = stripe.webhooks.constructEvent(
35
+ body,
36
+ request.headers.get("stripe-signature")!,
37
+ process.env.STRIPE_WEBHOOK_SECRET!
38
+ );
39
+
40
+ await tasks.trigger<typeof handleStripeEvent>("handle-stripe-event", event, {
41
+ // Retries of the same event start one run
42
+ idempotencyKey: event.id,
43
+ });
44
+
45
+ return Response.json({ received: true });
46
+ }
47
+ ```
48
+
49
+ Return quickly: the task runs in the background, so the provider gets its response before the work starts.
50
+
51
+ Set `TRIGGER_SECRET_KEY` in your app to a named [**Trigger only**](/apikeys) API key from the Trigger.dev environment the app uses, so the route can trigger tasks but do nothing else.
52
+
53
+ ## Framework guides
54
+
55
+ <CardGroup cols={2}>
56
+ <Card title="Custom webhook handler with Next.js" icon="N" href="/guides/frameworks/nextjs-webhooks">
57
+ Handle a webhook in a Next.js API route and trigger a task.
58
+ </Card>
59
+ <Card title="Custom webhook handler with Remix" icon="R" href="/guides/frameworks/remix-webhooks">
60
+ Handle a webhook in a Remix action and trigger a task.
61
+ </Card>
62
+ </CardGroup>
@@ -0,0 +1,13 @@
1
+ ---
2
+ title: "Webhooks pricing and limits"
3
+ sidebarTitle: "Pricing & limits"
4
+ description: "What webhooks cost on Trigger.dev Cloud, which plan limits apply, and how to run them self-hosted."
5
+ ---
6
+
7
+ Webhooks have no separate charge on Trigger.dev Cloud. Receiving, verifying, filtering and recording deliveries is included in every plan. The runs a delivery starts or resumes are billed like any other run: a per-run invocation cost plus compute time. See [pricing](https://trigger.dev/pricing).
8
+
9
+ A delivery that no subscriber's filter matches starts no run, so it adds no run cost. A run already [waiting](/webhooks/waiters) for that webhook still resumes and is billed like any other run. A run [waiting](/webhooks/waiters) for a webhook is suspended, so it uses no compute until the webhook arrives.
10
+
11
+ 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).
12
+
13
+ Webhooks are open source, so they also work self-hosted. See [Self-hosting webhooks](/self-hosting/env/webapp#webhooks) to turn them on.