@trigger.dev/sdk 4.7.4 → 4.7.6

package/docs/webhooks/sources.mdx

@@ -0,0 +1,224 @@
+---
+title: "Sources and verification"
+description: "Choose an endpoint's source, configure verification, and type the event its subscribers receive."
+sidebarTitle: "Sources & verification"
+---
+
+import WebhooksBetaBanner from "/snippets/webhooks-beta-banner.mdx";
+
+<WebhooksBetaBanner />
+
+An endpoint's `source` defines how Trigger.dev verifies requests and types the event every subscriber receives. Choose a named provider source or supply a verification configuration with `webhooks.custom()`.
+
+## Presets
+
+Presets supply the verification configuration, and most also carry the provider's part of the endpoint's [setup prompt](/webhooks/connect#set-it-up-with-an-ai-agent). Set the endpoint's signing secret or public key as described in [Connect a provider](/webhooks/connect).
+
+<CodeGroup>
+
+```ts /trigger/stripe.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const stripe = webhooks.endpoint.define({ id: "stripe", source: webhooks.stripe() });
+
+export const stripeEvents = webhook({
+  id: "stripe-events",
+  endpoint: stripe,
+  onEvent: async ({ event }) => {
+    if (event.type === "payment_intent.succeeded") {
+      console.log(event.id);
+    }
+  },
+});
+```
+
+```ts /trigger/github.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const github = webhooks.endpoint.define({ id: "github", source: webhooks.github() });
+
+export const githubEvents = webhook({
+  id: "github-events",
+  endpoint: github,
+  onEvent: async ({ headers }) => {
+    // GitHub puts the event type in a header
+    console.log(headers.get("x-github-event"));
+  },
+});
+```
+
+```ts /trigger/svix.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const svix = webhooks.endpoint.define({ id: "svix", source: webhooks.svix() });
+
+export const svixEvents = webhook({
+  id: "svix-events",
+  endpoint: svix,
+  onEvent: async ({ event }) => {
+    console.log(event);
+  },
+});
+```
+
+```ts /trigger/composio.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const composio = webhooks.endpoint.define({ id: "composio", source: webhooks.standardWebhooks() });
+
+export const composioEvents = webhook({
+  id: "composio-events",
+  endpoint: composio,
+  onEvent: async ({ event }) => {
+    console.log(event);
+  },
+});
+```
+
+</CodeGroup>
+
+The available presets are `stripe()`, `github()`, `svix()`, `standardWebhooks()`, `square()`, and `discord()`.
+
+### Svix and Standard Webhooks
+
+`svix()` and `standardWebhooks()` use HMAC-SHA256 over `id.timestamp.body` with a base64-encoded `whsec_` secret. Their header names differ:
+
+| Source | Headers |
+| --- | --- |
+| `svix()` | `svix-id`, `svix-timestamp`, `svix-signature` |
+| `standardWebhooks()` | `webhook-id`, `webhook-timestamp`, `webhook-signature` |
+
+Named sources such as `webhooks.clerk()` and `webhooks.composio()` select the corresponding configuration.
+
+## Named providers
+
+Each function below returns a source with its provider's verification configuration. Call it through `webhooks`, for example `webhooks.calCom()`.
+
+| Verification | Source functions |
+| --- | --- |
+| Svix | `clerk()`, `resend()`, `brex()`, `autumn()` |
+| Standard Webhooks | `openai()`, `replicate()`, `recallai()`, `composio()`, `loops()`, `granola()` |
+| HMAC-SHA256 with `X-Hub-Signature-256` | `whatsapp()` |
+| Shared secret in `X-Gitlab-Token` | `gitlab()` |
+| Shared secret as `Authorization: Bearer` | `supabase()` |
+| Provider-specific HMAC | `calendly()`, `calCom()`, `sentry()`, `pagerduty()`, `vercel()`, `linear()`, `notion()`, `typeform()`, `docusign()`, `jira()`, `intercom()`, `zendesk()`, `attio()`, `workos()`, `elevenlabs()`, `vapi()`, `retell()`, `shopify()`, `metronome()`, `mux()`, `tailscale()`, `langfuse()`, `infisical()`, `planetscale()`, `plain()`, `firecrawl()` |
+
+Provider IDs containing a hyphen use a camel case function name: the `cal-com` provider is `webhooks.calCom()`.
+
+Supabase database webhooks aren't signed, so `supabase()` checks a shared secret instead. Generate the endpoint's secret on Trigger.dev, then add an `Authorization` header with the value `Bearer <secret>` under the webhook's HTTP Headers in Supabase.
+
+Slack also ships as a chat channel in `@trigger.dev/slack`.
+
+## Endpoint validation
+
+Some sources also define a response for the provider's endpoint-validation request. These requests don't create deliveries or task runs.
+
+`discord()` answers a verified `{ type: 0 }` PING with HTTP `204` and no body. It also returns `204` for accepted events and `401` for invalid signatures. Set the Discord application's public key as the endpoint's verification credential.
+
+Slack's `url_verification` challenge is handled the same way by `@trigger.dev/slack`.
+
+`whatsapp()` answers Meta's GET verification request when `hub.mode` is `subscribe` and `hub.verify_token` matches the endpoint's verify token. It returns `hub.challenge` as text. The verify token is separate from the App Secret used to verify event signatures; see [Verify a WhatsApp endpoint URL](/webhooks/connect#verify-a-whatsapp-endpoint-url). Endpoints without GET verification return `405` to GET requests.
+
+## Custom providers
+
+`webhooks.custom()` accepts a verification configuration. This source verifies an HMAC-SHA256 signature over the raw body in `x-webhook-signature` and uses the event's `id` for deduplication:
+
+```ts /trigger/internal.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const internal = webhooks.endpoint.define({
+  id: "internal",
+  source: webhooks.custom<{ id: string; message: string }>(
+    {
+      scheme: "hmac",
+      algorithm: "sha256",
+      encoding: "hex",
+      signatureHeader: "x-webhook-signature",
+      signingString: "raw",
+      idempotencyField: { from: "body", name: "id" },
+    },
+    { setupPrompt: "Add the URL under Settings > Webhooks in the admin app and paste the secret there." }
+  ),
+});
+
+export const internalEvents = webhook({
+  id: "internal-events",
+  endpoint: internal,
+  onEvent: async ({ event }) => {
+    console.log(event.message);
+  },
+});
+```
+
+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.
+
+### Form-encoded bodies
+
+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.
+
+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:
+
+```ts /trigger/forms.ts
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const forms = webhooks.endpoint.define({
+  id: "forms",
+  source: webhooks.custom<{ command: string; text: string; user_id: string }>(
+    { scheme: "url-secret", placement: "query", paramName: "token" },
+    { response: { acceptedBody: "empty" } }
+  ),
+});
+
+export const commands = webhook({
+  id: "commands",
+  endpoint: forms,
+  filter: "event.command == '/deploy'",
+  onEvent: async ({ event }) => {
+    console.log(event.user_id, event.text);
+  },
+});
+```
+
+## Typing the event
+
+Stripe and GitHub sources provide default event shapes; other sources default to `unknown`. Pass an event type to the source function for typed handler parameters and autocomplete. This example uses `Stripe.Event` from the `stripe` package, which must be installed in your project:
+
+```ts /trigger/stripe.ts
+import type Stripe from "stripe";
+import { webhook, webhooks } from "@trigger.dev/sdk";
+
+export const stripe = webhooks.endpoint.define({ id: "stripe", source: webhooks.stripe<Stripe.Event>() });
+
+export const stripeEvents = webhook({
+  id: "stripe-events",
+  endpoint: stripe,
+  onEvent: async ({ event }) => {
+    console.log(event.type, event.id);
+  },
+});
+```
+
+For `webhooks.custom<T>()`, pass your own event type as `T`. The endpoint's event type flows to every subscriber: `webhook()` handlers, `chat.event` keys and filters, and [waiter](/webhooks/waiters) `match` paths are all checked against it.
+
+<Note>
+  Event types are compile-time annotations. Signature verification doesn't validate the body against
+  a TypeScript type. Validate `event` inside `onEvent` if your handler needs runtime schema checks.
+</Note>
+
+## Verification schemes
+
+Requests must pass verification before they reach any subscriber. Sources can check a signature or credential, enforce a timestamp tolerance, and derive an idempotency key for [deduplication](/webhooks/deliveries#deduplication). Verification failures return the source's rejected HTTP status (`400` by default).
+
+Custom sources support these schemes:
+
+| Scheme | Verification |
+| --- | --- |
+| `hmac` | Computes an HMAC over the raw body or a signing template and compares it with a request header. |
+| `shared-secret` | Compares a static token supplied in a header, bearer token, basic authentication, or request body. |
+| `url-secret` | Compares a token in a URL query parameter. Hosted endpoints don't support path placement. |
+| `asymmetric` | Verifies an Ed25519, ECDSA, or RSA signature using the provider's public key. |
+
+<Warning>
+  Query parameters can appear in access logs, proxies, and traces. Prefer a header-based scheme when
+  the provider supports one.
+</Warning>

package/docs/webhooks/waiters.mdx

@@ -0,0 +1,194 @@
+---
+title: "Waiting for a webhook"
+description: "Pause a run until a matching webhook arrives on an endpoint, then resume it with the verified event."
+sidebarTitle: "Waiters"
+---
+
+import WebhooksBetaBanner from "/snippets/webhooks-beta-banner.mdx";
+
+<WebhooksBetaBanner />
+
+**A waiter pauses a run until a matching delivery arrives on an [endpoint](/webhooks/overview).** Use it when your task starts something in another system and needs to know when that system reports back: a payment that settles, a build that finishes, a document that gets signed.
+
+```ts /trigger/checkout.ts
+import { task, webhooks } from "@trigger.dev/sdk";
+import { stripe } from "./stripe"; // webhooks.endpoint.define({ id: "stripe", source: webhooks.stripe() })
+
+export const checkout = task({
+  id: "checkout",
+  run: async ({
+    orderId,
+    customerId,
+    paymentMethodId,
+  }: {
+    orderId: string;
+    customerId: string;
+    paymentMethodId: string;
+  }) => {
+    const waiter = await webhooks.waiter.create(stripe, {
+      match: {
+        "event.type": "payment_intent.succeeded",
+        "event.data.object.metadata.orderId": orderId,
+      },
+      timeout: "1h",
+      // the same waiter (and its event) if this run is retried
+      idempotencyKey: `payment-${orderId}`,
+    });
+
+    // confirm: true charges the customer's saved payment method now, so Stripe sends payment_intent.succeeded.
+    // Stripe's own idempotency key stops a retry from creating a second intent for the order.
+    await stripeClient.paymentIntents.create(
+      {
+        amount: 4200,
+        currency: "usd",
+        customer: customerId,
+        payment_method: paymentMethodId,
+        confirm: true,
+        metadata: { orderId },
+      },
+      { idempotencyKey: `payment-intent-${orderId}` }
+    );
+
+    const { event, deliveryId } = await webhooks.waiter.wait(waiter).unwrap();
+    return { paymentIntent: event.data.object.id, deliveryId };
+  },
+});
+```
+
+While the run waits it is suspended, so it uses no compute. The endpoint's other subscribers still receive the delivery.
+
+## Create before you act
+
+A waiter only matches deliveries that arrive after it was created. Create it before the call that makes the provider send the webhook, as above, or a fast provider can deliver the event before anything is waiting for it.
+
+Match on values you control, such as your own order id in the provider object's metadata. Two runs waiting for the same values are both resumed by the delivery.
+
+## Matching
+
+`match` maps paths to the scalar each must equal. Paths use the same namespaces as a [filter](/webhooks/filters):
+
+| Path | Reads |
+| --- | --- |
+| `event.*` | The verified event body, for example `event.data.object.id`. |
+| `header.*` | A request header, matched case-insensitively, for example `header.x-shop-domain`. |
+| `webhook.*` | The endpoint: `id`, `source`, `externalRef`, `tenantId`, or `deliveryId`. |
+
+A waiter can match up to five paths, and each value is a string, number or boolean. Paths are checked against the endpoint's event type at build time: an unknown field on a typed event, a path to an object, or a path without a namespace is a type error. The API refuses the same paths at create time.
+
+For conditions that aren't equality, add a `filter`. It is checked after `match`:
+
+```ts
+await webhooks.waiter.create(stripe, {
+  match: { "event.data.object.metadata.orderId": orderId },
+  filter: "event.type in ['payment_intent.succeeded', 'payment_intent.payment_failed']",
+});
+```
+
+## The result
+
+`webhooks.waiter.wait(waiter)` returns a result you can check, and `.unwrap()` returns the output or throws:
+
+```ts
+const result = await webhooks.waiter.wait(waiter);
+if (result.ok) {
+  console.log(result.output.event, result.output.headers, result.output.endpoint);
+} else {
+  console.log(result.error.name); // "WaitpointTimeoutError" or "WebhookWaiterCancelledError"
+}
+```
+
+| Output field | Value |
+| --- | --- |
+| `event` | The verified event body, typed by the endpoint's source. |
+| `headers` | The request headers, with credentials such as signatures removed. |
+| `deliveryId` | The delivery that resumed the run (`whd_...`). |
+| `endpoint` | The endpoint the delivery arrived on. |
+
+`timeout` accepts a duration such as `"30m"` or a `Date`. It defaults to 24 hours and can be up to 90 days. A waiter that times out fails the wait with `WaitpointTimeoutError`.
+
+A waiter is a [waitpoint](/wait-for-token): its id starts with `waitpoint_` and it is tagged `webhook:<endpoint id>` plus any `tags` you pass (up to 10).
+
+## Providers that take a callback URL
+
+Some providers accept a webhook URL per request instead of one account-wide URL, such as Replicate's `webhook` parameter. Omit `match` and the waiter gets its own URL:
+
+```ts
+const waiter = await webhooks.waiter.create(replicateEndpoint, { timeout: "2h" });
+
+await replicate.predictions.create({ version, input, webhook: waiter.url });
+
+const { event } = await webhooks.waiter.wait(waiter).unwrap();
+```
+
+A delivery to `waiter.url` is verified with the endpoint's source, resumes only that waiter, and is not sent to the endpoint's subscribers.
+
+## Creating from your backend
+
+`webhooks.waiter.create` also works outside a run, for example in the API route that starts a checkout. Pass the waiter, or its id, to a task that waits on it:
+
+```ts
+const waiter = await webhooks.waiter.create(stripe, { match: { "event.data.object.metadata.orderId": orderId } });
+await fulfillWhenPaid.trigger({ waiterId: waiter.id });
+```
+
+```ts
+export const fulfillWhenPaid = task({
+  id: "fulfill-when-paid",
+  run: async ({ waiterId }: { waiterId: string }) => {
+    const { event } = await webhooks.waiter.wait(waiterId).unwrap();
+  },
+});
+```
+
+The same operations are on the REST API: [`POST /api/v1/webhooks/endpoints/{endpointId}/waiters`](/management/webhooks/create-waiter) with `match`, `filter`, `timeout`, `tags` and `idempotencyKey`, and [`POST /api/v1/webhooks/waiters/{waiterId}/cancel`](/management/webhooks/cancel-waiter). `endpointId` is the endpoint's declared id or its `wh_` id.
+
+## Retries and idempotency
+
+Pass an `idempotencyKey` so a task can be retried without losing its webhook. A create with a key it has seen returns the original waiter, with `isCached: true`, even if it has already completed, and waiting on a completed waiter returns its event straight away. Inside a task a string key is scoped to the run, as it is for [`trigger()`](/idempotency), so a retried attempt gets the waiter (and the event) the attempt before it created:
+
+```ts
+const waiter = await webhooks.waiter.create(stripe, {
+  match: { "event.data.object.metadata.orderId": orderId },
+  idempotencyKey: `payment-${orderId}`,
+});
+```
+
+Use [`idempotencyKeys.create(key, { scope })`](/idempotency) for a key scoped to one attempt or shared across runs, and `idempotencyKeyTTL` to set how long the key lasts.
+
+Without a key every call creates a new waiter, and a waiter only matches deliveries that arrive after it. If an attempt fails after its webhook arrived, the retry's new waiter waits for an event the provider already sent.
+
+## Cancelling
+
+`webhooks.waiter.cancel(waiter)` frees the waiter's slot and fails its wait with `WebhookWaiterCancelledError`. If a delivery has already claimed the waiter, the cancel is too late and the run resumes with that delivery:
+
+```ts
+const result = await webhooks.waiter.cancel(waiter);
+if (!result.cancelled) {
+  console.log("Already resumed by", result.deliveryId); // result.reason is "too_late"
+}
+```
+
+## Errors
+
+`webhooks.waiter.create` throws a typed error when nothing was created:
+
+| Error | Cause |
+| --- | --- |
+| `WebhookWaiterLimitError` | A limit was reached. `reason` is `endpoint_limit`, `environment_limit`, `shape_limit` or `timeout_too_long`. |
+| `WebhookEndpointNotFoundError` | The endpoint isn't in the environment's current deployment. |
+| `WebhookFilterError` | The `filter` doesn't parse. |
+
+## Limits
+
+| Limit | Default |
+| --- | --- |
+| Live waiters per endpoint | 10,000. This is also the most one delivery can resume. |
+| Live waiters per environment | 1,000,000 on self-hosted installs. |
+| Distinct sets of `match` paths per endpoint | 25 |
+| Paths per `match` | 5 |
+| Tags per waiter | 10 |
+| Timeout | 24 hours by default, 90 days at most |
+
+On Trigger.dev Cloud the per-endpoint and per-environment limits depend on your plan. Self-hosted installs can change them with `WEBHOOK_WAITER_MAX_PER_ENDPOINT`, `WEBHOOK_WAITER_MAX_PER_ENVIRONMENT` and `WEBHOOK_WAITER_MAX_SHAPES`.
+
+A delivery that resumes waiters shows one **Waiting runs** row on its [delivery page](/webhooks/deliveries#where-a-delivery-went) with how many matched, resumed and failed. A delivery that arrives while runs are waiting but matches none of them, and no subscriber takes, is `UNMATCHED`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trigger.dev/sdk",
-  "version": "4.7.4",
+  "version": "4.7.6",
   "description": "trigger.dev Node.JS SDK",
   "license": "MIT",
   "publishConfig": {
@@ -69,12 +69,13 @@
   "dependencies": {
     "@opentelemetry/api": "1.9.1",
     "@opentelemetry/semantic-conventions": "1.41.1",
-    "@trigger.dev/core": "4.7.4",
+    "@trigger.dev/core": "4.7.6",
     "uncrypto": "^0.1.3"
   },
   "devDependencies": {
     "@ai-sdk/provider": "3.0.8",
     "@arethetypeswrong/cli": "^0.18.5",
+    "@opentelemetry/sdk-trace-base": "2.8.0",
     "@types/react": "^19.2.14",
     "ai": "^6.0.116",
     "ai-v7": "npm:ai@7.0.0-canary.159",