@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
@@ -0,0 +1,91 @@
1
+ ---
2
+ title: "Connect to Snowflake"
3
+ sidebarTitle: "Snowflake"
4
+ description: "Connect to Snowflake from your tasks with workload identity federation instead of a password or private key."
5
+ ---
6
+
7
+ Use Snowflake [workload identity federation](https://docs.snowflake.com/en/user-guide/workload-identity-federation) to connect as a service user that trusts your Trigger.dev environment. The Snowflake driver sends the OIDC token itself, so there's no exchange step and no `SNOWFLAKE_PASSWORD` or private key stored anywhere.
8
+
9
+ Follow the [OIDC prerequisites](/oidc#prerequisites), then go to the [OIDC](https://cloud.trigger.dev/_/oidc) page for your environment and copy the issuer URL and subject.
10
+
11
+ ## Configure Snowflake
12
+
13
+ Create a service user for each environment. Replace the issuer and subject with the values from the dashboard:
14
+
15
+ ```sql
16
+ CREATE USER trigger_production
17
+ WORKLOAD_IDENTITY = (
18
+ TYPE = OIDC
19
+ ISSUER = 'https://oidc.trigger.dev/YOUR_ORG_SLUG'
20
+ SUBJECT = 'YOUR_ENVIRONMENT_SUBJECT'
21
+ )
22
+ TYPE = SERVICE
23
+ DEFAULT_ROLE = analytics_reader;
24
+
25
+ GRANT ROLE analytics_reader TO USER trigger_production;
26
+ ```
27
+
28
+ With no `OIDC_AUDIENCE_LIST`, Snowflake expects the audience `snowflakecomputing.com`, which the task requests below. `SUBJECT` can be up to 255 characters, which fits every Trigger.dev subject in practice.
29
+
30
+ ## Connect in your task
31
+
32
+ Workload identity needs the Snowflake Node.js driver with `WORKLOAD_IDENTITY` support:
33
+
34
+ <CodeGroup>
35
+
36
+ ```bash npm
37
+ npm i @trigger.dev/sdk@latest snowflake-sdk@latest
38
+ ```
39
+
40
+ ```bash pnpm
41
+ pnpm add @trigger.dev/sdk@latest snowflake-sdk@latest
42
+ ```
43
+
44
+ ```bash bun
45
+ bun add @trigger.dev/sdk@latest snowflake-sdk@latest
46
+ ```
47
+
48
+ </CodeGroup>
49
+
50
+ Set the [authentication options](https://docs.snowflake.com/en/developer-guide/node-js/nodejs-driver-authenticate) `authenticator`, `workloadIdentityProvider`, and `token`:
51
+
52
+ ```ts /trigger/query-snowflake.ts
53
+ import { auth, task } from "@trigger.dev/sdk";
54
+ import snowflake from "snowflake-sdk";
55
+
56
+ export const querySnowflake = task({
57
+ id: "query-snowflake",
58
+ run: async () => {
59
+ const { token } = await auth.getOIDCToken({ audience: "snowflakecomputing.com" });
60
+
61
+ const connection = snowflake.createConnection({
62
+ account: "YOUR_ACCOUNT_IDENTIFIER",
63
+ authenticator: "WORKLOAD_IDENTITY",
64
+ workloadIdentityProvider: "OIDC",
65
+ token,
66
+ });
67
+ // connect reports a failed login through its callback, so reject on it
68
+ await new Promise((resolve, reject) =>
69
+ connection.connect((err, conn) => (err ? reject(err) : resolve(conn)))
70
+ );
71
+
72
+ const rows = await new Promise((resolve, reject) =>
73
+ connection.execute({
74
+ sqlText: "SELECT CURRENT_USER()",
75
+ complete: (err, _stmt, rows) => (err ? reject(err) : resolve(rows)),
76
+ })
77
+ );
78
+
79
+ await new Promise((resolve) => connection.destroy(resolve));
80
+ return { rows };
81
+ },
82
+ });
83
+ ```
84
+
85
+ The token is only used to open the connection, so request it right before connecting. Open the connection inside `run` and close it before the run ends.
86
+
87
+ ## Remove the old credential
88
+
89
+ Once runs in every deployed environment connect this way, delete `SNOWFLAKE_PASSWORD`, `SNOWFLAKE_PRIVATE_KEY`, `SNOWFLAKE_PRIVATE_KEY_PATH`, and `SNOWFLAKE_PRIVATE_KEY_PASSPHRASE` from those environments on the Environment Variables page, then remove the password or key from the old Snowflake user. `SNOWFLAKE_ACCOUNT` isn't a secret and can stay.
90
+
91
+ Local Development runs can't mint OIDC tokens. Use your own Snowflake login there when `ctx.environment.type === "DEVELOPMENT"`.
@@ -0,0 +1,71 @@
1
+ ---
2
+ title: "Connect to HashiCorp Vault"
3
+ sidebarTitle: "Vault"
4
+ description: "Log in to Vault from your tasks with JWT auth instead of a long-lived Vault token."
5
+ ---
6
+
7
+ Use Vault's [JWT auth method](https://developer.hashicorp.com/vault/docs/auth/jwt) to exchange a Trigger.dev OIDC token for a short-lived Vault token. Your tasks read secrets with no `VAULT_TOKEN` stored anywhere. This works with self-managed Vault and HCP Vault.
8
+
9
+ Follow the [OIDC prerequisites](/oidc#prerequisites), then go to the [OIDC](https://cloud.trigger.dev/_/oidc) page for your environment and copy the issuer URL and subject.
10
+
11
+ ## Configure Vault
12
+
13
+ Enable the JWT auth method and point it at your issuer's discovery document:
14
+
15
+ ```bash
16
+ vault auth enable -path=trigger jwt
17
+
18
+ vault write auth/trigger/config \
19
+ oidc_discovery_url="https://oidc.trigger.dev/YOUR_ORG_SLUG" \
20
+ bound_issuer="https://oidc.trigger.dev/YOUR_ORG_SLUG"
21
+ ```
22
+
23
+ Create a role for each environment. Replace the subject with the **complete subject copied from the dashboard**, and the policy with one that allows only the paths your task reads:
24
+
25
+ ```bash
26
+ vault write auth/trigger/role/trigger-production \
27
+ role_type="jwt" \
28
+ bound_audiences="vault" \
29
+ bound_subject="YOUR_ENVIRONMENT_SUBJECT" \
30
+ user_claim="sub" \
31
+ token_policies="trigger-production" \
32
+ token_ttl="15m"
33
+ ```
34
+
35
+ `bound_audiences` is the audience your task requests; `vault` is an example, any value works if both sides match. See the [JWT auth API](https://developer.hashicorp.com/vault/api-docs/auth/jwt#create-update-role) for every role option.
36
+
37
+ ## Read a secret in your task
38
+
39
+ ```ts /trigger/read-from-vault.ts
40
+ import { auth, task } from "@trigger.dev/sdk";
41
+
42
+ const vaultAddr = "https://vault.example.com:8200";
43
+
44
+ export const readFromVault = task({
45
+ id: "read-from-vault",
46
+ run: async () => {
47
+ const { token: jwt } = await auth.getOIDCToken({ audience: "vault" });
48
+
49
+ const login = await fetch(`${vaultAddr}/v1/auth/trigger/login`, {
50
+ method: "POST",
51
+ body: JSON.stringify({ role: "trigger-production", jwt }),
52
+ });
53
+ if (!login.ok) throw new Error(`Vault login failed: ${login.status}`);
54
+ const { auth: vaultAuth } = await login.json();
55
+
56
+ const secret = await fetch(`${vaultAddr}/v1/secret/data/my-app`, {
57
+ headers: { "X-Vault-Token": vaultAuth.client_token },
58
+ });
59
+ const { data } = await secret.json();
60
+ // Use data.data here. Never log or return it.
61
+ },
62
+ });
63
+ ```
64
+
65
+ The login response holds the Vault token at `auth.client_token`. On HCP Vault or Vault Enterprise, add an `X-Vault-Namespace` header to both requests. Log in inside `run`, and log in again if the run outlives `token_ttl`.
66
+
67
+ ## Remove the old credential
68
+
69
+ Once runs in every deployed environment log in this way, delete `VAULT_TOKEN` from those environments on the Environment Variables page and revoke the old token with `vault token revoke`.
70
+
71
+ Local Development runs can't mint OIDC tokens. Use your own Vault login there when `ctx.environment.type === "DEVELOPMENT"`.
package/docs/oidc.mdx CHANGED
@@ -34,6 +34,8 @@ Choose an official integration, or connect a service that supports external OIDC
34
34
 
35
35
  For other services, follow [Custom integrations](/oidc/custom) to request a token and implement the service's authentication flow.
36
36
 
37
+ The OIDC page in the dashboard lists the environment variables in your project that hold credentials OIDC could replace, such as `AWS_ACCESS_KEY_ID` or `ANTHROPIC_API_KEY`, grouped by service with a link to each service's guide. The same keys are listed under **Replace with OIDC** on the environment variables [Needs attention page](/deploy-environment-variables#values-that-need-attention).
38
+
37
39
  ## Prerequisites
38
40
 
39
41
  - Use `@trigger.dev/sdk` and the Trigger.dev CLI (`trigger.dev`) **4.8.3 or later**, including the CLI used in CI.
@@ -347,7 +347,7 @@ export const myTask = task({
347
347
  run: async (payload: { prompt: string }) => {
348
348
  const completion = await openai.chat.completions.create({
349
349
  messages: [{ role: "user", content: payload.prompt }],
350
- model: "gpt-3.5-turbo",
350
+ model: "gpt-6-luna",
351
351
  stream: true,
352
352
  });
353
353
 
@@ -364,6 +364,8 @@ We patch the latest released version line only, so keep an eye on new releases t
364
364
 
365
365
  You can also lock the versions of the bundled services, for example with `CLICKHOUSE_IMAGE_TAG`. If you do, or if you bring your own ClickHouse via `CLICKHOUSE_URL`, note that Trigger.dev requires ClickHouse 25.8 or newer.
366
366
 
367
+ The optional `LOGS_SEARCH_INSERT_ASYNC` setting defaults to `false` and requires ClickHouse 26.2 or newer when enabled. Leave it disabled on ClickHouse 25.8.
368
+
367
369
  <Note>
368
370
  The bundled ClickHouse uses the official `clickhouse/clickhouse-server` image, and your existing
369
371
  data volume carries over automatically on upgrade. If you pinned `CLICKHOUSE_IMAGE_TAG` to a
@@ -11,6 +11,8 @@ mode: "wide"
11
11
  | `SESSION_SECRET` | Yes | — | Session encryption secret. Run: `openssl rand -hex 16` |
12
12
  | `MAGIC_LINK_SECRET` | Yes | — | Magic link encryption secret. Run: `openssl rand -hex 16` |
13
13
  | `ENCRYPTION_KEY` | Yes | — | Secret store encryption key. Run: `openssl rand -hex 16` |
14
+ | `ENVIRONMENT_ENCRYPTION_ENABLED` | No | false | Master gate for automatic per-environment encryption enrollment. Also requires `environmentEncryptionEnabled` in organization feature flags or the global feature flag (organization overrides global; unset is false). Enable only after all instances have been upgraded. Existing encrypted environments continue using their keys if any rollout gate is later disabled. |
15
+ | `ENVIRONMENT_ENCRYPTION_KMS_KEY_ARN` | No | unset | Resolved symmetric AWS KMS key ARN for wrapping new environments' keys. Unset uses `ENCRYPTION_KEYRING` (or the legacy `ENCRYPTION_KEY`) locally, without AWS access. Changing this does not alter existing environment-key versions. |
14
16
  | `MANAGED_WORKER_SECRET` | Yes | — | Managed worker secret. Must be set and match supervisor. Run: `openssl rand -hex 32` |
15
17
  | `PUBLIC_TOKEN_SUBJECT_SECRET` | No | `ENCRYPTION_KEY` | Key that encrypts the environment id inside public access tokens. Set it to keep this separate from the secret store key. Run: `openssl rand -hex 32` |
16
18
  | `PUBLIC_TOKEN_SEALED_SUBJECT_ENABLED` | No | false | Encrypt the environment id inside newly minted public access tokens. Turn on only once every webapp instance runs a version that can read them. |
@@ -47,7 +49,7 @@ mode: "wide"
47
49
  | `BLOCKED_EMAIL_DOMAINS` | No | — | Comma-separated email domains that can't sign in or sign up, including their subdomains. |
48
50
  | `LOGIN_RATE_LIMITS_ENABLED` | No | true | Enable rate limiting on magic-link login. |
49
51
  | `MAGIC_LINK_SAME_BROWSER_REQUIRED` | No | true | Only accept a magic link opened in the browser that requested it. Set to false to allow opening it on another device.|
50
- | `PERSONAL_ACCESS_TOKEN_EXPIRY_DAYS` | No | 30,90,365 | Lifetimes, in days (1 to 3650), offered when creating a personal access token on the dashboard. Comma-separated. |
52
+ | `PERSONAL_ACCESS_TOKEN_EXPIRY_DAYS` | No | 30,90,365 | Lifetimes, in days (1 to 3650), offered when creating a personal access token on the dashboard. Comma-separated. The longest is also the furthest a custom expiry date can be. |
51
53
  | `PERSONAL_ACCESS_TOKEN_DEFAULT_EXPIRY_DAYS` | No | 90 | The lifetime preselected when creating a personal access token. If it isn't one of the offered lifetimes, the shortest is preselected. |
52
54
  | `CLI_LOGIN_IDLE_TIMEOUT_DAYS` | No | 7 | A token minted by a CLI or MCP login stops working after this many days without use. Set to 0 to turn this off. Each token keeps the value it was minted with. |
53
55
  | `PERSONAL_ACCESS_TOKEN_EXPIRY_EMAILS_ENABLED` | No | true | Email the owner 7 days before a dashboard-created personal access token expires, and again when it has. Only runs when `EMAIL_TRANSPORT` is set. |
@@ -168,6 +170,7 @@ mode: "wide"
168
170
  | `STREAMING_BATCH_MAX_ITEMS` | No | 1000 | Max items in streaming batch (v3 API, requires SDK 4.3.1+). |
169
171
  | `STREAMING_BATCH_ITEM_MAXIMUM_SIZE` | No | 3145728 (3MB) | Max size per item in streaming batch. |
170
172
  | `STREAMING_BATCH_INGEST_CONCURRENCY` | No | 10 | Items ingested concurrently per streaming batch request. Peak memory ≈ this × item size. Set to 1 for sequential. |
173
+ | `ENVIRONMENT_VARIABLES_COMPARE_MAX_KEYS` | No | 1000 | Most keys one environment variables comparison compares, and most values the Needs attention page checks for empty ones. Above it the dashboard asks to search or pick fewer keys. |
171
174
  | **OTel limits** | | | |
172
175
  | `TRIGGER_OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT` | No | 1024 | OTel span attribute count limit. |
173
176
  | `TRIGGER_OTEL_LOG_ATTRIBUTE_COUNT_LIMIT` | No | 1024 | OTel log attribute count limit. |
@@ -320,6 +320,8 @@ Migration from the old Bitnami subchart to the official `clickhouse/clickhouse-s
320
320
  ClickHouse externally for a clustered or replicated setup.
321
321
  </Note>
322
322
 
323
+ The optional `LOGS_SEARCH_INSERT_ASYNC` setting defaults to `false` and requires ClickHouse 26.2 or newer when enabled. Leave it disabled on ClickHouse 25.8.
324
+
323
325
  **Direct configuration:**
324
326
 
325
327
  ```yaml
@@ -87,7 +87,7 @@ Prefer building the tool with the AI SDK’s [`tool()`](https://sdk.vercel.ai/do
87
87
  ```ts
88
88
  import { ai } from "@trigger.dev/sdk/ai";
89
89
  import { schemaTask } from "@trigger.dev/sdk";
90
- import { tool, generateText } from "ai";
90
+ import { tool, generateText, stepCountIs } from "ai";
91
91
  import { openai } from "@ai-sdk/openai";
92
92
  import { z } from "zod";
93
93
 
@@ -115,24 +115,25 @@ export const myAiTask = schemaTask({
115
115
  run: async ({ text }) => {
116
116
  const { text: reply } = await generateText({
117
117
  prompt: text,
118
- model: openai("gpt-4o"),
118
+ model: openai("gpt-6-luna"),
119
119
  tools: {
120
120
  myTool,
121
121
  },
122
+ stopWhen: stepCountIs(5),
122
123
  });
123
124
  return reply;
124
125
  },
125
126
  });
126
127
  ```
127
128
 
128
- `experimental_toToolResultContent` and other tool-level options belong on **`tool({ ... })`**, not on `ai.toolExecute`:
129
+ `toModelOutput` and other tool-level options belong on **`tool({ ... })`**, not on `ai.toolExecute`:
129
130
 
130
131
  ```ts
131
132
  import { openai } from "@ai-sdk/openai";
132
133
  import { Sandbox } from "@e2b/code-interpreter";
133
134
  import { ai } from "@trigger.dev/sdk/ai";
134
135
  import { schemaTask } from "@trigger.dev/sdk";
135
- import { generateObject, tool } from "ai";
136
+ import { generateText, Output, tool } from "ai";
136
137
  import { z } from "zod";
137
138
 
138
139
  const chartTask = schemaTask({
@@ -142,17 +143,19 @@ const chartTask = schemaTask({
142
143
  input: z.string().describe("The chart to generate"),
143
144
  }),
144
145
  run: async ({ input }) => {
145
- const code = await generateObject({
146
- model: openai("gpt-4o"),
147
- schema: z.object({
148
- code: z.string().describe("The Python code to execute"),
146
+ const { output } = await generateText({
147
+ model: openai("gpt-6-luna"),
148
+ output: Output.object({
149
+ schema: z.object({
150
+ code: z.string().describe("The Python code to execute"),
151
+ }),
149
152
  }),
150
153
  system: `You are a helpful assistant that generates matplotlib code. End with plt.show().`,
151
154
  prompt: input,
152
155
  });
153
156
 
154
157
  const sandbox = await Sandbox.create();
155
- const execution = await sandbox.runCode(code.object.code);
158
+ const execution = await sandbox.runCode(output.code);
156
159
  const firstResult = execution.results[0];
157
160
 
158
161
  if (firstResult.png) {
@@ -162,16 +165,26 @@ const chartTask = schemaTask({
162
165
  },
163
166
  });
164
167
 
168
+ // Keep the executor in its own const so `output` below is typed from the task
169
+ const executeChart = ai.toolExecute(chartTask);
170
+
165
171
  export const chartTool = tool({
166
172
  description: chartTask.description ?? "",
167
173
  inputSchema: chartTask.schema!,
168
- execute: ai.toolExecute(chartTask),
169
- experimental_toToolResultContent: (result) => [
170
- { type: "image", data: result.chart, mimeType: "image/png" },
171
- ],
174
+ execute: executeChart,
175
+ toModelOutput: ({ output }) => ({
176
+ type: "content",
177
+ value: [
178
+ { type: "file", mediaType: "image/png", data: { type: "data", data: output.chart } },
179
+ ],
180
+ }),
172
181
  });
173
182
  ```
174
183
 
184
+ <Note>
185
+ This sample uses AI SDK 7. On AI SDK 6, use `{ type: "image-data", data: output.chart, mediaType: "image/png" }` as the item in `value` instead of the `file` part. On AI SDK 5, pass `experimental_output: Output.object(...)` instead of `output` and read the result from `experimental_output`, and use `toModelOutput: (output) => ({ type: "content", value: [{ type: "media", data: output.chart, mediaType: "image/png" }] })`.
186
+ </Note>
187
+
175
188
  Inside the task run, you can read tool execution context with **`ai.currentToolOptions()`** (and helpers like `ai.toolCallId()`, `ai.chatContext()` when running inside a [`chat.agent`](/ai-chat/overview)):
176
189
 
177
190
  ```ts
@@ -402,7 +402,7 @@ export async function POST(req: Request) {
402
402
  const { messages, runId } = await req.json();
403
403
 
404
404
  const result = streamText({
405
- model: openai("gpt-4o"),
405
+ model: openai("gpt-6-luna"),
406
406
  messages,
407
407
  });
408
408
 
@@ -686,7 +686,7 @@ export const generateAI = task({
686
686
  id: "generate-ai",
687
687
  run: async (payload: { prompt: string }) => {
688
688
  const result = streamText({
689
- model: openai("gpt-4o"),
689
+ model: openai("gpt-6-luna"),
690
690
  prompt: payload.prompt,
691
691
  });
692
692
 
@@ -53,6 +53,13 @@ If you see "Connection error" when running `trigger login` (or "Failed to create
53
53
  2. **VPN or firewall:** Disconnect from VPN or check firewall/proxy; try `npx trigger.dev@latest login --log-level debug` for more detail.
54
54
  3. **TLS / certificate store:** Node may use a different CA store than your OS (e.g. `curl` works but the CLI fails). Try `export NODE_EXTRA_CA_CERTS=/etc/ssl/cert.pem` (macOS/Linux) then login again, or reinstall Node so it gets updated certs. Behind a corporate proxy or custom CA? Set `NODE_EXTRA_CA_CERTS` to that CA file.
55
55
 
56
+ ### `personal_access_token_expired` or `cli_login_expired`
57
+
58
+ If a request fails with `401` and one of these codes, the token has expired:
59
+
60
+ - **`personal_access_token_expired`**: a personal access token from the dashboard reached the expiry date chosen when it was created. Create a new one on the [Personal Access Tokens](https://cloud.trigger.dev/account/tokens) page and replace the old one wherever it's stored. See [PAT expiry](/management/authentication#pat-expiry).
61
+ - **`cli_login_expired`**: a CLI or MCP login went unused for 7 days. Run `npx trigger.dev@latest login`. With a CLI version before 4.8.4, `login` can't replace an expired login, so run `trigger.dev logout` first. See [CLI login expiry](/cli-login-commands#login-expiry).
62
+
56
63
  ### Runs never dequeue in dev
57
64
 
58
65
  If runs sit in the queue and never start while running `trigger.dev dev`, check whether you have more than one local instance running against the same project. Each project has a single dev environment, and only one `trigger.dev dev` instance can consume from it at a time, so a second instance causes runs to be split between them and some appear stuck. Keep a single `trigger.dev dev` running per project. [Upvote isolated dev sessions](https://triggerdev.featurebase.app/p/isolated-dev-sessions-for-multiple-local-trigger-dev-instances) if you need to run multiple local instances.
@@ -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>