@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
@@ -1,70 +0,0 @@
1
- ---
2
- title: "Webhooks public beta"
3
- description: "Webhooks are available to every organization in the normal Trigger.dev release. Install the packages, see what may change before general availability, and send feedback."
4
- sidebarTitle: "Public beta"
5
- ---
6
-
7
- **Webhooks are in public beta: every organization can use them, and they ship in the normal Trigger.dev release.** Endpoints you declare sync when you deploy or run `trigger dev`, and they show up on each environment's **Webhooks** page.
8
-
9
- ## What public beta means
10
-
11
- - The API may still change before general availability. We announce changes in the [changelog](https://trigger.dev/changelog).
12
- - Webhooks are open source, so they work self-hosted too. See [Self-hosting webhooks](/self-hosting/env/webapp#webhooks) to turn them on.
13
-
14
- ## Install the packages
15
-
16
- Webhooks are in `@trigger.dev/sdk` 4.8.1 and later. Install the SDK and the CLI from `@latest`:
17
-
18
- <CodeGroup>
19
-
20
- ```bash npm
21
- npm i @trigger.dev/sdk@latest
22
- npm i -D trigger.dev@latest
23
- ```
24
-
25
- ```bash pnpm
26
- pnpm add @trigger.dev/sdk@latest
27
- pnpm add -D trigger.dev@latest
28
- ```
29
-
30
- ```bash bun
31
- bun add @trigger.dev/sdk@latest
32
- bun add -D trigger.dev@latest
33
- ```
34
-
35
- </CodeGroup>
36
-
37
- Add the connector packages if you're building Slack or Linear agents:
38
-
39
- <CodeGroup>
40
-
41
- ```bash npm
42
- npm i @trigger.dev/slack@latest @trigger.dev/linear@latest
43
- ```
44
-
45
- ```bash pnpm
46
- pnpm add @trigger.dev/slack@latest @trigger.dev/linear@latest
47
- ```
48
-
49
- ```bash bun
50
- bun add @trigger.dev/slack@latest @trigger.dev/linear@latest
51
- ```
52
-
53
- </CodeGroup>
54
-
55
- The webhook tools in the [MCP server](/mcp-introduction) come with the CLI, so a current `trigger.dev` install has them.
56
-
57
- ## Moving from a private beta build
58
-
59
- If you installed from the `webhooks` npm tag, switch every Trigger.dev package to `@latest`, including `@trigger.dev/build` if your project has it. Versions like `4.8.0-webhooks.20261020092920` are older than 4.8.1. You can also remove any minimum release age exemption you added for the beta builds, and reinstall the MCP server without `--tag webhooks`.
60
-
61
- ## Get started
62
-
63
- - [Overview](/webhooks/overview): endpoints, sources, and what can subscribe.
64
- - [Connect a provider](/webhooks/connect): register the URL and signing secret, then check that events arrive.
65
- - [Slack agents](/webhooks/slack) and [Linear agents](/webhooks/linear): turn a `chat.agent` into an agent that lives in Slack or Linear.
66
- - [Deliveries and endpoints](/webhooks/deliveries): inspect payloads, replay deliveries, and see the runs each one started.
67
-
68
- ## Feedback
69
-
70
- Send bugs, questions and ideas to [eric@trigger.dev](mailto:eric@trigger.dev). Delivery ids (`whd_...`) and run ids help us find what happened.
@@ -1,252 +0,0 @@
1
- ---
2
- title: "Sources and verification"
3
- description: "Choose an endpoint's source, configure verification, and type the event its subscribers receive."
4
- sidebarTitle: "Sources & verification"
5
- ---
6
-
7
- An endpoint's `source` defines how Trigger.dev verifies requests and types the event every subscriber receives. Choose a named provider source or supply a verification configuration with `webhooks.custom()`.
8
-
9
- ## Presets
10
-
11
- Presets supply the verification configuration, and most also carry the provider's part of the endpoint's [setup prompt](/webhooks/connect#set-it-up-with-an-ai-agent). Set the endpoint's signing secret or public key as described in [Connect a provider](/webhooks/connect).
12
-
13
- <CodeGroup>
14
-
15
- ```ts /trigger/stripe.ts
16
- import { webhook, webhooks } from "@trigger.dev/sdk";
17
-
18
- export const stripe = webhooks.endpoint.define({ id: "stripe", source: webhooks.stripe() });
19
-
20
- export const stripeEvents = webhook({
21
- id: "stripe-events",
22
- endpoint: stripe,
23
- onEvent: async ({ event }) => {
24
- if (event.type === "payment_intent.succeeded") {
25
- console.log(event.id);
26
- }
27
- },
28
- });
29
- ```
30
-
31
- ```ts /trigger/github.ts
32
- import { webhook, webhooks } from "@trigger.dev/sdk";
33
-
34
- export const github = webhooks.endpoint.define({ id: "github", source: webhooks.github() });
35
-
36
- export const githubEvents = webhook({
37
- id: "github-events",
38
- endpoint: github,
39
- onEvent: async ({ headers }) => {
40
- // GitHub puts the event type in a header
41
- console.log(headers.get("x-github-event"));
42
- },
43
- });
44
- ```
45
-
46
- ```ts /trigger/svix.ts
47
- import { webhook, webhooks } from "@trigger.dev/sdk";
48
-
49
- export const svix = webhooks.endpoint.define({ id: "svix", source: webhooks.svix() });
50
-
51
- export const svixEvents = webhook({
52
- id: "svix-events",
53
- endpoint: svix,
54
- onEvent: async ({ event }) => {
55
- console.log(event);
56
- },
57
- });
58
- ```
59
-
60
- ```ts /trigger/composio.ts
61
- import { webhook, webhooks } from "@trigger.dev/sdk";
62
-
63
- export const composio = webhooks.endpoint.define({ id: "composio", source: webhooks.standardWebhooks() });
64
-
65
- export const composioEvents = webhook({
66
- id: "composio-events",
67
- endpoint: composio,
68
- onEvent: async ({ event }) => {
69
- console.log(event);
70
- },
71
- });
72
- ```
73
-
74
- </CodeGroup>
75
-
76
- The available presets are `stripe()`, `github()`, `svix()`, `standardWebhooks()`, `square()`, and `discord()`.
77
-
78
- ### Svix and Standard Webhooks
79
-
80
- `svix()` and `standardWebhooks()` use HMAC-SHA256 over `id.timestamp.body` with a base64-encoded `whsec_` secret. Their header names differ:
81
-
82
- | Source | Headers |
83
- | --- | --- |
84
- | `svix()` | `svix-id`, `svix-timestamp`, `svix-signature` |
85
- | `standardWebhooks()` | `webhook-id`, `webhook-timestamp`, `webhook-signature` |
86
-
87
- Named sources such as `webhooks.clerk()` and `webhooks.composio()` select the corresponding configuration.
88
-
89
- ## Named providers
90
-
91
- Each function below returns a source with its provider's verification configuration. Call it through `webhooks`, for example `webhooks.calCom()`.
92
-
93
- | Verification | Source functions |
94
- | --- | --- |
95
- | Svix | `clerk()`, `resend()`, `brex()`, `autumn()` |
96
- | Standard Webhooks | `openai()`, `replicate()`, `recallai()`, `composio()`, `loops()`, `granola()` |
97
- | HMAC-SHA256 with `X-Hub-Signature-256` | `whatsapp()` |
98
- | Shared secret in `X-Gitlab-Token` | `gitlab()` |
99
- | Shared secret as `Authorization: Bearer` | `supabase()` |
100
- | Hookdeck relay (HMAC-SHA256 with `X-Hookdeck-Signature`) | `hookdeck()` |
101
- | Provider-specific HMAC | `calendly()`, `calCom()`, `sentry()`, `pagerduty()`, `vercel()`, `linear()`, `notion()`, `typeform()`, `docusign()`, `jira()`, `intercom()`, `zendesk()`, `attio()`, `workos()`, `elevenlabs()`, `vapi()`, `retell()`, `shopify()`, `metronome()`, `mux()`, `tailscale()`, `langfuse()`, `infisical()`, `planetscale()`, `plain()`, `firecrawl()` |
102
-
103
- Provider IDs containing a hyphen use a camel case function name: the `cal-com` provider is `webhooks.calCom()`.
104
-
105
- Supabase database webhooks aren't signed, so `supabase()` checks a shared secret instead. Generate the endpoint's secret on Trigger.dev, then add an `Authorization` header with the value `Bearer <secret>` under the webhook's HTTP Headers in Supabase.
106
-
107
- Slack also ships as a chat channel in `@trigger.dev/slack`.
108
-
109
- For a complete project built on `resend()`, see the [Resend email agent example](https://github.com/triggerdotdev/examples/tree/main/resend-slack-email-agent). It drafts replies to a Resend inbox and waits for your approval in Slack before sending them.
110
-
111
- ### Hookdeck
112
-
113
- `hookdeck()` verifies requests that a [Hookdeck](https://hookdeck.com) connection forwards to the endpoint. Hookdeck forwards the original provider's body unchanged, so pass that provider's event type:
114
-
115
- ```ts /trigger/stripe-via-hookdeck.ts
116
- import type Stripe from "stripe";
117
- import { webhook, webhooks } from "@trigger.dev/sdk";
118
-
119
- export const stripeViaHookdeck = webhooks.endpoint.define({
120
- id: "stripe-via-hookdeck",
121
- source: webhooks.hookdeck<Stripe.Event>(),
122
- });
123
-
124
- export const paymentSucceeded = webhook({
125
- id: "payment-succeeded",
126
- endpoint: stripeViaHookdeck,
127
- filter: "event.type == 'payment_intent.succeeded'",
128
- onEvent: async ({ event }) => {
129
- console.log(event.id);
130
- },
131
- });
132
- ```
133
-
134
- Use the endpoint URL as the connection's HTTP destination, keep the destination's authentication on Hookdeck Signature (the default for new destinations), and store the Hookdeck project's signing secret from **Settings > Secrets** as the endpoint's signing secret.
135
-
136
- - **Secret rotation:** when you roll the signing secret in Hookdeck with an expiry, Hookdeck also signs each request with the previous secret in `X-Hookdeck-Signature-2`, so deliveries keep verifying until you store the new secret.
137
- - **Deduplication:** retries dedupe on `X-Hookdeck-Eventid`, which is the same on every attempt of a Hookdeck event.
138
- - **Custom header prefix:** if you changed the header prefix in the Hookdeck project's settings, pass it with `webhooks.hookdeck({ headerPrefix: "x-acme" })`. The prefix renames the event id header; the signature headers keep the `X-Hookdeck-` name.
139
-
140
- ## Endpoint validation
141
-
142
- Some sources also define a response for the provider's endpoint-validation request. These requests don't create deliveries or task runs.
143
-
144
- `discord()` answers a verified `{ type: 0 }` PING with HTTP `204` and no body. It also returns `204` for accepted events and `401` for invalid signatures. Set the Discord application's public key as the endpoint's verification credential.
145
-
146
- Slack's `url_verification` challenge is handled the same way by `@trigger.dev/slack`.
147
-
148
- `whatsapp()` answers Meta's GET verification request when `hub.mode` is `subscribe` and `hub.verify_token` matches the endpoint's verify token. It returns `hub.challenge` as text. The verify token is separate from the App Secret used to verify event signatures; see [Verify a WhatsApp endpoint URL](/webhooks/connect#verify-a-whatsapp-endpoint-url). Endpoints without GET verification return `405` to GET requests.
149
-
150
- ## Custom providers
151
-
152
- `webhooks.custom()` accepts a verification configuration. This source verifies an HMAC-SHA256 signature over the raw body in `x-webhook-signature` and uses the event's `id` for deduplication:
153
-
154
- ```ts /trigger/internal.ts
155
- import { webhook, webhooks } from "@trigger.dev/sdk";
156
-
157
- export const internal = webhooks.endpoint.define({
158
- id: "internal",
159
- source: webhooks.custom<{ id: string; message: string }>(
160
- {
161
- scheme: "hmac",
162
- algorithm: "sha256",
163
- encoding: "hex",
164
- signatureHeader: "x-webhook-signature",
165
- signingString: "raw",
166
- idempotencyField: { from: "body", name: "id" },
167
- },
168
- { setupPrompt: "Add the URL under Settings > Webhooks in the admin app and paste the secret there." }
169
- ),
170
- });
171
-
172
- export const internalEvents = webhook({
173
- id: "internal-events",
174
- endpoint: internal,
175
- onEvent: async ({ event }) => {
176
- console.log(event.message);
177
- },
178
- });
179
- ```
180
-
181
- 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.
182
-
183
- ### Form-encoded bodies
184
-
185
- 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.
186
-
187
- 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:
188
-
189
- ```ts /trigger/forms.ts
190
- import { webhook, webhooks } from "@trigger.dev/sdk";
191
-
192
- export const forms = webhooks.endpoint.define({
193
- id: "forms",
194
- source: webhooks.custom<{ command: string; text: string; user_id: string }>(
195
- { scheme: "url-secret", placement: "query", paramName: "token" },
196
- { response: { acceptedBody: "empty" } }
197
- ),
198
- });
199
-
200
- export const commands = webhook({
201
- id: "commands",
202
- endpoint: forms,
203
- filter: "event.command == '/deploy'",
204
- onEvent: async ({ event }) => {
205
- console.log(event.user_id, event.text);
206
- },
207
- });
208
- ```
209
-
210
- ## Typing the event
211
-
212
- Stripe and GitHub sources provide default event shapes; other sources default to `unknown`. Pass an event type to the source function for typed handler parameters and autocomplete. This example uses `Stripe.Event` from the `stripe` package, which must be installed in your project:
213
-
214
- ```ts /trigger/stripe.ts
215
- import type Stripe from "stripe";
216
- import { webhook, webhooks } from "@trigger.dev/sdk";
217
-
218
- export const stripe = webhooks.endpoint.define({ id: "stripe", source: webhooks.stripe<Stripe.Event>() });
219
-
220
- export const stripeEvents = webhook({
221
- id: "stripe-events",
222
- endpoint: stripe,
223
- onEvent: async ({ event }) => {
224
- console.log(event.type, event.id);
225
- },
226
- });
227
- ```
228
-
229
- For `webhooks.custom<T>()`, pass your own event type as `T`. The endpoint's event type flows to every subscriber: `webhook()` handlers, `chat.event` keys and filters, and [waiter](/webhooks/waiters) `match` paths are all checked against it.
230
-
231
- <Note>
232
- Event types are compile-time annotations. Signature verification doesn't validate the body against
233
- a TypeScript type. Validate `event` inside `onEvent` if your handler needs runtime schema checks.
234
- </Note>
235
-
236
- ## Verification schemes
237
-
238
- Requests must pass verification before they reach any subscriber. Sources can check a signature or credential, enforce a timestamp tolerance, and derive an idempotency key for [deduplication](/webhooks/deliveries#deduplication). Verification failures return the source's rejected HTTP status (`400` by default).
239
-
240
- Custom sources support these schemes:
241
-
242
- | Scheme | Verification |
243
- | --- | --- |
244
- | `hmac` | Computes an HMAC over the raw body or a signing template and compares it with a request header. |
245
- | `shared-secret` | Compares a static token supplied in a header, bearer token, basic authentication, or request body. |
246
- | `url-secret` | Compares a token in a URL query parameter. Hosted endpoints don't support path placement. |
247
- | `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. |
248
-
249
- <Warning>
250
- Query parameters can appear in access logs, proxies, and traces. Prefer a header-based scheme when
251
- the provider supports one.
252
- </Warning>