@trigger.dev/sdk 4.8.4 → 4.8.6

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 (187) hide show
  1. package/dist/commonjs/v3/ai.d.ts +29 -5
  2. package/dist/commonjs/v3/ai.js +160 -114
  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 +35 -12
  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/webhooks.d.ts +8 -2
  28. package/dist/commonjs/v3/webhooks.js +20 -11
  29. package/dist/commonjs/v3/webhooks.js.map +1 -1
  30. package/dist/commonjs/version.js +1 -1
  31. package/dist/esm/v3/ai.d.ts +29 -5
  32. package/dist/esm/v3/ai.js +162 -117
  33. package/dist/esm/v3/ai.js.map +1 -1
  34. package/dist/esm/v3/auth.d.ts +4 -4
  35. package/dist/esm/v3/auth.js +22 -76
  36. package/dist/esm/v3/auth.js.map +1 -1
  37. package/dist/esm/v3/chat-client.d.ts +1 -1
  38. package/dist/esm/v3/chat.d.ts +1 -1
  39. package/dist/esm/v3/prompt.js +6 -8
  40. package/dist/esm/v3/prompt.js.map +1 -1
  41. package/dist/esm/v3/runs.d.ts +5 -1
  42. package/dist/esm/v3/runs.js.map +1 -1
  43. package/dist/esm/v3/sessions.js +10 -7
  44. package/dist/esm/v3/sessions.js.map +1 -1
  45. package/dist/esm/v3/shared.d.ts +2 -2
  46. package/dist/esm/v3/shared.js +16 -15
  47. package/dist/esm/v3/shared.js.map +1 -1
  48. package/dist/esm/v3/steeringContext.d.ts +35 -10
  49. package/dist/esm/v3/steeringContext.js +34 -12
  50. package/dist/esm/v3/steeringContext.js.map +1 -1
  51. package/dist/esm/v3/streams.js +10 -8
  52. package/dist/esm/v3/streams.js.map +1 -1
  53. package/dist/esm/v3/tasks.d.ts +2 -2
  54. package/dist/esm/v3/tasks.js.map +1 -1
  55. package/dist/esm/v3/test/mock-chat-agent.js +25 -14
  56. package/dist/esm/v3/test/mock-chat-agent.js.map +1 -1
  57. package/dist/esm/v3/webhooks.d.ts +8 -2
  58. package/dist/esm/v3/webhooks.js +20 -11
  59. package/dist/esm/v3/webhooks.js.map +1 -1
  60. package/dist/esm/version.js +1 -1
  61. package/docs/ai/observability.mdx +25 -19
  62. package/docs/ai/prompts.mdx +25 -19
  63. package/docs/ai-chat/actions.mdx +1 -1
  64. package/docs/ai-chat/anatomy.mdx +1 -1
  65. package/docs/ai-chat/backend.mdx +24 -24
  66. package/docs/ai-chat/background-injection.mdx +5 -5
  67. package/docs/ai-chat/chat-local.mdx +2 -2
  68. package/docs/ai-chat/compaction.mdx +38 -15
  69. package/docs/ai-chat/custom-agents.mdx +4 -4
  70. package/docs/ai-chat/error-handling.mdx +4 -4
  71. package/docs/ai-chat/fast-starts.mdx +8 -7
  72. package/docs/ai-chat/frontend.mdx +6 -2
  73. package/docs/ai-chat/lifecycle-hooks.mdx +11 -11
  74. package/docs/ai-chat/migrating-from-a-route-handler.mdx +4 -4
  75. package/docs/ai-chat/migrating-from-hydrate-messages.mdx +1 -1
  76. package/docs/ai-chat/overview.mdx +1 -1
  77. package/docs/ai-chat/patterns/branching-conversations.mdx +1 -1
  78. package/docs/ai-chat/patterns/database-persistence.mdx +2 -2
  79. package/docs/ai-chat/patterns/human-in-the-loop.mdx +1 -1
  80. package/docs/ai-chat/patterns/native-compaction.mdx +29 -9
  81. package/docs/ai-chat/patterns/persistence-and-replay.mdx +1 -1
  82. package/docs/ai-chat/patterns/redacting-telemetry.mdx +2 -2
  83. package/docs/ai-chat/patterns/skills.mdx +2 -2
  84. package/docs/ai-chat/patterns/sub-agents.mdx +1 -1
  85. package/docs/ai-chat/patterns/tool-result-auditing.mdx +1 -1
  86. package/docs/ai-chat/patterns/trusted-edge-signals.mdx +2 -2
  87. package/docs/ai-chat/patterns/version-upgrades.mdx +2 -2
  88. package/docs/ai-chat/pending-messages.mdx +5 -5
  89. package/docs/ai-chat/prompt-caching.mdx +7 -7
  90. package/docs/ai-chat/quick-start.mdx +2 -2
  91. package/docs/ai-chat/testing.mdx +9 -9
  92. package/docs/ai-chat/tools.mdx +9 -5
  93. package/docs/ai-chat/transcript-storage.mdx +2 -2
  94. package/docs/ai-chat/types.mdx +10 -3
  95. package/docs/apikeys.mdx +2 -1
  96. package/docs/cli-login-commands.mdx +12 -0
  97. package/docs/concurrency.mdx +40 -0
  98. package/docs/database-connections.mdx +1 -1
  99. package/docs/deploy-environment-variables.mdx +84 -2
  100. package/docs/deployment/trusted-publishing.mdx +4 -0
  101. package/docs/errors-retrying.mdx +25 -18
  102. package/docs/github-actions.mdx +1 -1
  103. package/docs/github-integration.mdx +21 -0
  104. package/docs/how-it-works.mdx +4 -2
  105. package/docs/introduction.mdx +1 -1
  106. package/docs/mcp-introduction.mdx +7 -1
  107. package/docs/mcp-remote.mdx +90 -0
  108. package/docs/oidc/azure.mdx +81 -0
  109. package/docs/oidc/databricks.mdx +99 -0
  110. package/docs/oidc/doppler.mdx +60 -0
  111. package/docs/oidc/gcp.mdx +109 -0
  112. package/docs/oidc/hugging-face.mdx +90 -0
  113. package/docs/oidc/openrouter.mdx +91 -0
  114. package/docs/oidc/snowflake.mdx +91 -0
  115. package/docs/oidc/vault.mdx +71 -0
  116. package/docs/oidc.mdx +2 -0
  117. package/docs/runs/metadata.mdx +1 -1
  118. package/docs/self-hosting/docker.mdx +2 -0
  119. package/docs/self-hosting/env/webapp.mdx +4 -1
  120. package/docs/self-hosting/kubernetes.mdx +2 -0
  121. package/docs/tasks/schemaTask.mdx +26 -13
  122. package/docs/tasks/streams.mdx +2 -2
  123. package/docs/troubleshooting.mdx +7 -0
  124. package/docs/webhooks/channels.mdx +6 -6
  125. package/docs/webhooks/connect.mdx +9 -75
  126. package/docs/webhooks/custom-providers.mdx +87 -0
  127. package/docs/webhooks/deliveries.mdx +7 -7
  128. package/docs/webhooks/filters.mdx +2 -2
  129. package/docs/webhooks/how-it-works.mdx +58 -0
  130. package/docs/webhooks/human-in-the-loop.mdx +3 -3
  131. package/docs/webhooks/linear.mdx +5 -3
  132. package/docs/webhooks/overview.mdx +20 -71
  133. package/docs/webhooks/own-handler.mdx +62 -0
  134. package/docs/webhooks/pricing-and-limits.mdx +13 -0
  135. package/docs/webhooks/providers/attio.mdx +38 -0
  136. package/docs/webhooks/providers/autumn.mdx +40 -0
  137. package/docs/webhooks/providers/cal-com.mdx +41 -0
  138. package/docs/webhooks/providers/calendly.mdx +41 -0
  139. package/docs/webhooks/providers/clerk.mdx +40 -0
  140. package/docs/webhooks/providers/discord.mdx +45 -0
  141. package/docs/webhooks/providers/docusign.mdx +41 -0
  142. package/docs/webhooks/providers/elevenlabs.mdx +41 -0
  143. package/docs/webhooks/providers/firecrawl.mdx +54 -0
  144. package/docs/webhooks/providers/github.mdx +46 -0
  145. package/docs/webhooks/providers/gitlab.mdx +41 -0
  146. package/docs/webhooks/providers/granola.mdx +44 -0
  147. package/docs/webhooks/providers/hookdeck.mdx +98 -0
  148. package/docs/webhooks/providers/infisical.mdx +41 -0
  149. package/docs/webhooks/providers/jira.mdx +41 -0
  150. package/docs/webhooks/providers/langfuse.mdx +40 -0
  151. package/docs/webhooks/providers/linear.mdx +45 -0
  152. package/docs/webhooks/providers/loops.mdx +40 -0
  153. package/docs/webhooks/providers/metronome.mdx +42 -0
  154. package/docs/webhooks/providers/mux.mdx +40 -0
  155. package/docs/webhooks/providers/openai.mdx +40 -0
  156. package/docs/webhooks/providers/pagerduty.mdx +40 -0
  157. package/docs/webhooks/providers/plain.mdx +41 -0
  158. package/docs/webhooks/providers/planetscale.mdx +40 -0
  159. package/docs/webhooks/providers/recall-ai.mdx +54 -0
  160. package/docs/webhooks/providers/replicate.mdx +41 -0
  161. package/docs/webhooks/providers/resend.mdx +44 -0
  162. package/docs/webhooks/providers/retell.mdx +41 -0
  163. package/docs/webhooks/providers/sentry.mdx +41 -0
  164. package/docs/webhooks/providers/shopify.mdx +49 -0
  165. package/docs/webhooks/providers/slack.mdx +48 -0
  166. package/docs/webhooks/providers/square.mdx +40 -0
  167. package/docs/webhooks/providers/stripe.mdx +86 -0
  168. package/docs/webhooks/providers/supabase.mdx +41 -0
  169. package/docs/webhooks/providers/tailscale.mdx +43 -0
  170. package/docs/webhooks/providers/typeform.mdx +42 -0
  171. package/docs/webhooks/providers/vapi.mdx +47 -0
  172. package/docs/webhooks/providers/vercel.mdx +40 -0
  173. package/docs/webhooks/providers/whatsapp.mdx +45 -0
  174. package/docs/webhooks/providers/workos.mdx +41 -0
  175. package/docs/webhooks/providers/zendesk.mdx +41 -0
  176. package/docs/webhooks/providers.mdx +53 -0
  177. package/docs/webhooks/quick-start.mdx +131 -0
  178. package/docs/webhooks/session-routing.mdx +6 -6
  179. package/docs/webhooks/signing-secrets.mdx +80 -0
  180. package/docs/webhooks/slack.mdx +11 -2
  181. package/docs/webhooks/verification.mdx +139 -0
  182. package/docs/webhooks/waiters.mdx +2 -2
  183. package/docs/webhooks/webhook-tasks.mdx +46 -0
  184. package/package.json +4 -5
  185. package/docs/migrating-from-v3.mdx +0 -332
  186. package/docs/webhooks/public-beta.mdx +0 -70
  187. package/docs/webhooks/sources.mdx +0 -252
@@ -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.
@@ -0,0 +1,38 @@
1
+ ---
2
+ title: "Attio webhooks"
3
+ sidebarTitle: "Attio"
4
+ description: "Receive and verify Attio webhooks with Trigger.dev. Check the HMAC-SHA256 signature in attio-signature and run a task for each Attio event."
5
+ ---
6
+
7
+ **`webhooks.attio()` verifies the HMAC-SHA256 signature Attio sends in `attio-signature` on every request.**
8
+
9
+ ```ts /trigger/attio.ts
10
+ import { webhook, webhooks } from "@trigger.dev/sdk";
11
+
12
+ export const attio = webhooks.endpoint.define({
13
+ id: "attio",
14
+ source: webhooks.attio(),
15
+ });
16
+
17
+ export const attioEvents = webhook({
18
+ id: "attio-events",
19
+ endpoint: attio,
20
+ onEvent: async ({ event }) => {
21
+ console.log(event);
22
+ },
23
+ });
24
+ ```
25
+
26
+ | Setting | Value |
27
+ | --- | --- |
28
+ | Source | `webhooks.attio()` |
29
+ | Verification | HMAC-SHA256 in `attio-signature` |
30
+ | Credential | Signing secret issued by Attio |
31
+ | Attio docs | [Attio webhook docs](https://docs.attio.com/rest-api/guides/webhooks) |
32
+
33
+ ## Set up Attio
34
+
35
+ 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page.
36
+ 2. In Attio's developer settings, open your integration and add a webhook with the webhook URL and the events your subscribers need. You can also create it with Attio's webhooks API.
37
+ 3. Attio generates the signing secret and returns it when the webhook is created; it's also shown in the developer settings. Copy it, then choose **Set signing secret** on the Trigger.dev endpoint.
38
+ 4. Send a test event from Attio, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives.
@@ -0,0 +1,40 @@
1
+ ---
2
+ title: "Autumn webhooks"
3
+ sidebarTitle: "Autumn"
4
+ description: "Receive and verify Autumn webhooks with Trigger.dev. Check the Svix signature and run a task for each Autumn event, filtered on event.type."
5
+ ---
6
+
7
+ **`webhooks.autumn()` verifies the Svix signature Autumn sends in the `svix-*` headers on every request.**
8
+
9
+ ```ts /trigger/autumn.ts
10
+ import { webhook, webhooks } from "@trigger.dev/sdk";
11
+
12
+ export const autumn = webhooks.endpoint.define({
13
+ id: "autumn",
14
+ source: webhooks.autumn(),
15
+ });
16
+
17
+ export const autumnEvents = webhook({
18
+ id: "autumn-events",
19
+ endpoint: autumn,
20
+ filter: "event.type == 'billing.updated'",
21
+ onEvent: async ({ event }) => {
22
+ console.log(event);
23
+ },
24
+ });
25
+ ```
26
+
27
+ | Setting | Value |
28
+ | --- | --- |
29
+ | Source | `webhooks.autumn()` |
30
+ | Verification | Svix (`svix-id`, `svix-timestamp`, `svix-signature`) |
31
+ | Credential | Signing secret issued by Autumn |
32
+ | Event type | `event.type` |
33
+ | Autumn docs | [Autumn webhook docs](https://docs.useautumn.com/documentation/webhooks) |
34
+
35
+ ## Set up Autumn
36
+
37
+ 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page.
38
+ 2. In the Autumn dashboard, open **Developer** and select the **Webhooks** tab. Choose **Add Endpoint**, enter the webhook URL and select the events your subscribers need.
39
+ 3. Copy the endpoint's signing secret (it starts with `whsec_`), then choose **Set signing secret** on the Trigger.dev endpoint.
40
+ 4. Choose **Send Test Event** in Autumn, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives.
@@ -0,0 +1,41 @@
1
+ ---
2
+ title: "Cal.com webhooks"
3
+ sidebarTitle: "Cal.com"
4
+ description: "Receive and verify Cal.com webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-cal-signature-256 and run a task for each Cal.com event, filtered on event.triggerEvent."
5
+ ---
6
+
7
+ **`webhooks.calCom()` verifies the HMAC-SHA256 signature Cal.com sends in `x-cal-signature-256` on every request.**
8
+
9
+ ```ts /trigger/cal-com.ts
10
+ import { webhook, webhooks } from "@trigger.dev/sdk";
11
+
12
+ export const calCom = webhooks.endpoint.define({
13
+ id: "cal-com",
14
+ source: webhooks.calCom(),
15
+ });
16
+
17
+ export const calComEvents = webhook({
18
+ id: "cal-com-events",
19
+ endpoint: calCom,
20
+ onEvent: async ({ event }) => {
21
+ console.log(event);
22
+ },
23
+ });
24
+ ```
25
+
26
+ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.triggerEvent`.
27
+
28
+ | Setting | Value |
29
+ | --- | --- |
30
+ | Source | `webhooks.calCom()` |
31
+ | Verification | HMAC-SHA256 in `x-cal-signature-256` |
32
+ | Credential | Secret you generate on Trigger.dev |
33
+ | Event type | `event.triggerEvent` |
34
+ | Cal.com docs | [Cal.com webhook docs](https://cal.com/docs/developing/guides/automation/webhooks) |
35
+
36
+ ## Set up Cal.com
37
+
38
+ 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page.
39
+ 2. Choose **Generate secret** on the Trigger.dev endpoint and copy the value.
40
+ 3. In Cal.com, open **Settings > Developer > Webhooks** and add a webhook with the webhook URL and the events your subscribers need. Paste the secret into its secret field. The secret is optional in Cal.com but required here: without it, Cal.com doesn't sign deliveries and every one is rejected. Cal.com hides the secret after you save.
41
+ 4. Send a test event from Cal.com, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives.
@@ -0,0 +1,41 @@
1
+ ---
2
+ title: "Calendly webhooks"
3
+ sidebarTitle: "Calendly"
4
+ description: "Receive and verify Calendly webhooks with Trigger.dev. Check the HMAC-SHA256 signature in calendly-webhook-signature and run a task for each Calendly event, filtered on event.event."
5
+ ---
6
+
7
+ **`webhooks.calendly()` verifies the HMAC-SHA256 signature Calendly sends in `calendly-webhook-signature` on every request.**
8
+
9
+ ```ts /trigger/calendly.ts
10
+ import { webhook, webhooks } from "@trigger.dev/sdk";
11
+
12
+ export const calendly = webhooks.endpoint.define({
13
+ id: "calendly",
14
+ source: webhooks.calendly(),
15
+ });
16
+
17
+ export const calendlyEvents = webhook({
18
+ id: "calendly-events",
19
+ endpoint: calendly,
20
+ onEvent: async ({ event }) => {
21
+ console.log(event);
22
+ },
23
+ });
24
+ ```
25
+
26
+ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event`.
27
+
28
+ | Setting | Value |
29
+ | --- | --- |
30
+ | Source | `webhooks.calendly()` |
31
+ | Verification | HMAC-SHA256 in `calendly-webhook-signature` |
32
+ | Credential | The `signing_key` you set on the subscription |
33
+ | Event type | `event.event` |
34
+ | Calendly docs | [Calendly webhook docs](https://developer.calendly.com/api-docs/overview/webhooks/webhook-signatures) |
35
+
36
+ ## Set up Calendly
37
+
38
+ 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page.
39
+ 2. Calendly webhooks are created through the API, on a paid plan. Choose a signing key (for example, the output of `openssl rand -hex 32`), then create the subscription with `POST https://api.calendly.com/webhook_subscriptions`, passing `url` (the webhook URL), `events`, `organization`, `scope` and `signing_key`. If you create the subscription from an OAuth app, Calendly generates the signing key instead.
40
+ 3. Choose **Set signing secret** on the Trigger.dev endpoint and paste the signing key.
41
+ 4. Send a test event from Calendly, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives.
@@ -0,0 +1,40 @@
1
+ ---
2
+ title: "Clerk webhooks"
3
+ sidebarTitle: "Clerk"
4
+ description: "Receive and verify Clerk webhooks with Trigger.dev. Check the Svix signature and run a task for each Clerk event, filtered on event.type."
5
+ ---
6
+
7
+ **`webhooks.clerk()` verifies the Svix signature Clerk sends in the `svix-*` headers on every request.**
8
+
9
+ ```ts /trigger/clerk.ts
10
+ import { webhook, webhooks } from "@trigger.dev/sdk";
11
+
12
+ export const clerk = webhooks.endpoint.define({
13
+ id: "clerk",
14
+ source: webhooks.clerk(),
15
+ });
16
+
17
+ export const clerkEvents = webhook({
18
+ id: "clerk-events",
19
+ endpoint: clerk,
20
+ filter: "event.type == 'user.created'",
21
+ onEvent: async ({ event }) => {
22
+ console.log(event);
23
+ },
24
+ });
25
+ ```
26
+
27
+ | Setting | Value |
28
+ | --- | --- |
29
+ | Source | `webhooks.clerk()` |
30
+ | Verification | Svix (`svix-id`, `svix-timestamp`, `svix-signature`) |
31
+ | Credential | Signing secret issued by Clerk |
32
+ | Event type | `event.type` |
33
+ | Clerk docs | [Clerk webhook docs](https://clerk.com/docs/guides/development/webhooks/overview) |
34
+
35
+ ## Set up Clerk
36
+
37
+ 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page.
38
+ 2. Add the webhook URL as an endpoint in Clerk's webhook settings and subscribe it to the event types your subscribers need.
39
+ 3. Copy the endpoint's signing secret (it starts with `whsec_`), then choose **Set signing secret** on the Trigger.dev endpoint.
40
+ 4. Send a test event from Clerk, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives.
@@ -0,0 +1,45 @@
1
+ ---
2
+ title: "Discord webhooks"
3
+ sidebarTitle: "Discord"
4
+ description: "Receive and verify Discord webhooks with Trigger.dev. Check the Ed25519 signature in x-signature-ed25519 and run a task for each Discord event, filtered on event.event.type."
5
+ ---
6
+
7
+ **`webhooks.discord()` verifies the Ed25519 signature Discord sends in `x-signature-ed25519` on every request.**
8
+
9
+ ```ts /trigger/discord.ts
10
+ import { webhook, webhooks } from "@trigger.dev/sdk";
11
+
12
+ export const discord = webhooks.endpoint.define({
13
+ id: "discord",
14
+ source: webhooks.discord(),
15
+ });
16
+
17
+ export const discordEvents = webhook({
18
+ id: "discord-events",
19
+ endpoint: discord,
20
+ onEvent: async ({ event }) => {
21
+ console.log(event);
22
+ },
23
+ });
24
+ ```
25
+
26
+ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event.type`.
27
+
28
+ | Setting | Value |
29
+ | --- | --- |
30
+ | Source | `webhooks.discord()` |
31
+ | Verification | Ed25519 signature in `x-signature-ed25519` |
32
+ | Credential | Discord's public key |
33
+ | Event type | `event.event.type` |
34
+ | Discord docs | [Discord webhook docs](https://docs.discord.com/developers/events/webhook-events) |
35
+
36
+ ## Set up Discord
37
+
38
+ 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page.
39
+ 2. In the [Discord Developer Portal](https://discord.com/developers/applications), open the application and copy the **Public Key** from its **General Information** page. Choose **Set public key** on the Trigger.dev endpoint and paste it.
40
+ 3. Open the application's **Webhooks** page. Set the **Endpoint URL** to the webhook URL, turn **Events** on, and select the event types your subscribers need. Discord sends a PING when you save, and the endpoint can only answer it once the public key is set.
41
+ 4. Send a test event from Discord, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives.
42
+
43
+ ## Endpoint validation
44
+
45
+ The endpoint answers Discord's verified PING with an empty `204`, so the PING creates no delivery or run.