@trigger.dev/sdk 4.8.5 → 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.
- package/dist/commonjs/v3/ai.d.ts +29 -5
- package/dist/commonjs/v3/ai.js +160 -114
- package/dist/commonjs/v3/ai.js.map +1 -1
- package/dist/commonjs/v3/auth.d.ts +4 -4
- package/dist/commonjs/v3/auth.js +21 -75
- package/dist/commonjs/v3/auth.js.map +1 -1
- package/dist/commonjs/v3/chat-client.d.ts +1 -1
- package/dist/commonjs/v3/chat.d.ts +1 -1
- package/dist/commonjs/v3/prompt.js +6 -8
- package/dist/commonjs/v3/prompt.js.map +1 -1
- package/dist/commonjs/v3/runs.d.ts +5 -1
- package/dist/commonjs/v3/runs.js.map +1 -1
- package/dist/commonjs/v3/sessions.js +10 -7
- package/dist/commonjs/v3/sessions.js.map +1 -1
- package/dist/commonjs/v3/shared.d.ts +2 -2
- package/dist/commonjs/v3/shared.js +16 -15
- package/dist/commonjs/v3/shared.js.map +1 -1
- package/dist/commonjs/v3/steeringContext.d.ts +35 -10
- package/dist/commonjs/v3/steeringContext.js +35 -12
- package/dist/commonjs/v3/steeringContext.js.map +1 -1
- package/dist/commonjs/v3/streams.js +10 -8
- package/dist/commonjs/v3/streams.js.map +1 -1
- package/dist/commonjs/v3/tasks.d.ts +2 -2
- package/dist/commonjs/v3/tasks.js.map +1 -1
- package/dist/commonjs/v3/test/mock-chat-agent.js +24 -13
- package/dist/commonjs/v3/test/mock-chat-agent.js.map +1 -1
- package/dist/commonjs/v3/webhooks.d.ts +8 -2
- package/dist/commonjs/v3/webhooks.js +20 -11
- package/dist/commonjs/v3/webhooks.js.map +1 -1
- package/dist/commonjs/version.js +1 -1
- package/dist/esm/v3/ai.d.ts +29 -5
- package/dist/esm/v3/ai.js +162 -117
- package/dist/esm/v3/ai.js.map +1 -1
- package/dist/esm/v3/auth.d.ts +4 -4
- package/dist/esm/v3/auth.js +22 -76
- package/dist/esm/v3/auth.js.map +1 -1
- package/dist/esm/v3/chat-client.d.ts +1 -1
- package/dist/esm/v3/chat.d.ts +1 -1
- package/dist/esm/v3/prompt.js +6 -8
- package/dist/esm/v3/prompt.js.map +1 -1
- package/dist/esm/v3/runs.d.ts +5 -1
- package/dist/esm/v3/runs.js.map +1 -1
- package/dist/esm/v3/sessions.js +10 -7
- package/dist/esm/v3/sessions.js.map +1 -1
- package/dist/esm/v3/shared.d.ts +2 -2
- package/dist/esm/v3/shared.js +16 -15
- package/dist/esm/v3/shared.js.map +1 -1
- package/dist/esm/v3/steeringContext.d.ts +35 -10
- package/dist/esm/v3/steeringContext.js +34 -12
- package/dist/esm/v3/steeringContext.js.map +1 -1
- package/dist/esm/v3/streams.js +10 -8
- package/dist/esm/v3/streams.js.map +1 -1
- package/dist/esm/v3/tasks.d.ts +2 -2
- package/dist/esm/v3/tasks.js.map +1 -1
- package/dist/esm/v3/test/mock-chat-agent.js +25 -14
- package/dist/esm/v3/test/mock-chat-agent.js.map +1 -1
- package/dist/esm/v3/webhooks.d.ts +8 -2
- package/dist/esm/v3/webhooks.js +20 -11
- package/dist/esm/v3/webhooks.js.map +1 -1
- package/dist/esm/version.js +1 -1
- package/docs/ai/observability.mdx +25 -19
- package/docs/ai/prompts.mdx +25 -19
- package/docs/ai-chat/actions.mdx +1 -1
- package/docs/ai-chat/anatomy.mdx +1 -1
- package/docs/ai-chat/backend.mdx +24 -24
- package/docs/ai-chat/background-injection.mdx +5 -5
- package/docs/ai-chat/chat-local.mdx +2 -2
- package/docs/ai-chat/compaction.mdx +38 -15
- package/docs/ai-chat/custom-agents.mdx +4 -4
- package/docs/ai-chat/error-handling.mdx +4 -4
- package/docs/ai-chat/fast-starts.mdx +8 -7
- package/docs/ai-chat/frontend.mdx +6 -2
- package/docs/ai-chat/lifecycle-hooks.mdx +11 -11
- package/docs/ai-chat/migrating-from-a-route-handler.mdx +4 -4
- package/docs/ai-chat/migrating-from-hydrate-messages.mdx +1 -1
- package/docs/ai-chat/overview.mdx +1 -1
- package/docs/ai-chat/patterns/branching-conversations.mdx +1 -1
- package/docs/ai-chat/patterns/database-persistence.mdx +2 -2
- package/docs/ai-chat/patterns/human-in-the-loop.mdx +1 -1
- package/docs/ai-chat/patterns/native-compaction.mdx +29 -9
- package/docs/ai-chat/patterns/persistence-and-replay.mdx +1 -1
- package/docs/ai-chat/patterns/redacting-telemetry.mdx +2 -2
- package/docs/ai-chat/patterns/skills.mdx +2 -2
- package/docs/ai-chat/patterns/sub-agents.mdx +1 -1
- package/docs/ai-chat/patterns/tool-result-auditing.mdx +1 -1
- package/docs/ai-chat/patterns/trusted-edge-signals.mdx +2 -2
- package/docs/ai-chat/patterns/version-upgrades.mdx +2 -2
- package/docs/ai-chat/pending-messages.mdx +5 -5
- package/docs/ai-chat/prompt-caching.mdx +7 -7
- package/docs/ai-chat/quick-start.mdx +2 -2
- package/docs/ai-chat/testing.mdx +9 -9
- package/docs/ai-chat/tools.mdx +9 -5
- package/docs/ai-chat/transcript-storage.mdx +2 -2
- package/docs/ai-chat/types.mdx +10 -3
- package/docs/apikeys.mdx +2 -1
- package/docs/cli-login-commands.mdx +12 -0
- package/docs/concurrency.mdx +40 -0
- package/docs/database-connections.mdx +1 -1
- package/docs/deploy-environment-variables.mdx +84 -2
- package/docs/deployment/trusted-publishing.mdx +4 -0
- package/docs/errors-retrying.mdx +25 -18
- package/docs/github-actions.mdx +1 -1
- package/docs/github-integration.mdx +21 -0
- package/docs/how-it-works.mdx +4 -2
- package/docs/introduction.mdx +1 -1
- package/docs/mcp-introduction.mdx +7 -1
- package/docs/mcp-remote.mdx +90 -0
- package/docs/oidc/azure.mdx +81 -0
- package/docs/oidc/databricks.mdx +99 -0
- package/docs/oidc/doppler.mdx +60 -0
- package/docs/oidc/gcp.mdx +109 -0
- package/docs/oidc/hugging-face.mdx +90 -0
- package/docs/oidc/openrouter.mdx +91 -0
- package/docs/oidc/snowflake.mdx +91 -0
- package/docs/oidc/vault.mdx +71 -0
- package/docs/oidc.mdx +2 -0
- package/docs/runs/metadata.mdx +1 -1
- package/docs/self-hosting/docker.mdx +2 -0
- package/docs/self-hosting/env/webapp.mdx +4 -1
- package/docs/self-hosting/kubernetes.mdx +2 -0
- package/docs/tasks/schemaTask.mdx +26 -13
- package/docs/tasks/streams.mdx +2 -2
- package/docs/troubleshooting.mdx +7 -0
- package/docs/webhooks/channels.mdx +6 -6
- package/docs/webhooks/connect.mdx +9 -75
- package/docs/webhooks/custom-providers.mdx +87 -0
- package/docs/webhooks/deliveries.mdx +7 -7
- package/docs/webhooks/filters.mdx +2 -2
- package/docs/webhooks/how-it-works.mdx +58 -0
- package/docs/webhooks/human-in-the-loop.mdx +3 -3
- package/docs/webhooks/linear.mdx +5 -3
- package/docs/webhooks/overview.mdx +20 -71
- package/docs/webhooks/own-handler.mdx +62 -0
- package/docs/webhooks/pricing-and-limits.mdx +13 -0
- package/docs/webhooks/providers/attio.mdx +38 -0
- package/docs/webhooks/providers/autumn.mdx +40 -0
- package/docs/webhooks/providers/cal-com.mdx +41 -0
- package/docs/webhooks/providers/calendly.mdx +41 -0
- package/docs/webhooks/providers/clerk.mdx +40 -0
- package/docs/webhooks/providers/discord.mdx +45 -0
- package/docs/webhooks/providers/docusign.mdx +41 -0
- package/docs/webhooks/providers/elevenlabs.mdx +41 -0
- package/docs/webhooks/providers/firecrawl.mdx +54 -0
- package/docs/webhooks/providers/github.mdx +46 -0
- package/docs/webhooks/providers/gitlab.mdx +41 -0
- package/docs/webhooks/providers/granola.mdx +44 -0
- package/docs/webhooks/providers/hookdeck.mdx +98 -0
- package/docs/webhooks/providers/infisical.mdx +41 -0
- package/docs/webhooks/providers/jira.mdx +41 -0
- package/docs/webhooks/providers/langfuse.mdx +40 -0
- package/docs/webhooks/providers/linear.mdx +45 -0
- package/docs/webhooks/providers/loops.mdx +40 -0
- package/docs/webhooks/providers/metronome.mdx +42 -0
- package/docs/webhooks/providers/mux.mdx +40 -0
- package/docs/webhooks/providers/openai.mdx +40 -0
- package/docs/webhooks/providers/pagerduty.mdx +40 -0
- package/docs/webhooks/providers/plain.mdx +41 -0
- package/docs/webhooks/providers/planetscale.mdx +40 -0
- package/docs/webhooks/providers/recall-ai.mdx +54 -0
- package/docs/webhooks/providers/replicate.mdx +41 -0
- package/docs/webhooks/providers/resend.mdx +44 -0
- package/docs/webhooks/providers/retell.mdx +41 -0
- package/docs/webhooks/providers/sentry.mdx +41 -0
- package/docs/webhooks/providers/shopify.mdx +49 -0
- package/docs/webhooks/providers/slack.mdx +48 -0
- package/docs/webhooks/providers/square.mdx +40 -0
- package/docs/webhooks/providers/stripe.mdx +86 -0
- package/docs/webhooks/providers/supabase.mdx +41 -0
- package/docs/webhooks/providers/tailscale.mdx +43 -0
- package/docs/webhooks/providers/typeform.mdx +42 -0
- package/docs/webhooks/providers/vapi.mdx +47 -0
- package/docs/webhooks/providers/vercel.mdx +40 -0
- package/docs/webhooks/providers/whatsapp.mdx +45 -0
- package/docs/webhooks/providers/workos.mdx +41 -0
- package/docs/webhooks/providers/zendesk.mdx +41 -0
- package/docs/webhooks/providers.mdx +53 -0
- package/docs/webhooks/quick-start.mdx +131 -0
- package/docs/webhooks/session-routing.mdx +6 -6
- package/docs/webhooks/signing-secrets.mdx +80 -0
- package/docs/webhooks/slack.mdx +11 -2
- package/docs/webhooks/verification.mdx +139 -0
- package/docs/webhooks/waiters.mdx +2 -2
- package/docs/webhooks/webhook-tasks.mdx +46 -0
- package/package.json +4 -5
- package/docs/migrating-from-v3.mdx +0 -332
- package/docs/webhooks/public-beta.mdx +0 -70
- 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.
|
package/docs/runs/metadata.mdx
CHANGED
|
@@ -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-
|
|
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-
|
|
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
|
-
`
|
|
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 {
|
|
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
|
|
146
|
-
model: openai("gpt-
|
|
147
|
-
|
|
148
|
-
|
|
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(
|
|
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:
|
|
169
|
-
|
|
170
|
-
|
|
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
|
package/docs/tasks/streams.mdx
CHANGED
|
@@ -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-
|
|
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-
|
|
689
|
+
model: openai("gpt-6-luna"),
|
|
690
690
|
prompt: payload.prompt,
|
|
691
691
|
});
|
|
692
692
|
|
package/docs/troubleshooting.mdx
CHANGED
|
@@ -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: "
|
|
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**
|
|
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-
|
|
30
|
+
streamText({ model: anthropic("claude-sonnet-5-5"), messages }),
|
|
31
31
|
});
|
|
32
32
|
```
|
|
33
33
|
|
|
34
|
-
The `run()` loop is
|
|
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`,
|
|
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
|
-
|
|
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
|
|
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.
|
|
62
|
-
|
|
63
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
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>
|