@trigger.dev/sdk 4.7.4 → 4.8.0-webhooks.20261020092920

package/dist/esm/v3/webhooks.d.ts

@@ -1,4 +1,8 @@
 import { Webhook } from "@trigger.dev/core/v3";
+import type { WebhookSource, InferWebhookEvent, AnyWebhookSource, ValidateWebhookFilter, NarrowWebhookEvent, ChatEvent, ValidatedWebhookKey, WebhookResponseConfig, WebhookUrlSecretConfig, WebhookVerifierConfig, StripeWebhookEvent, GitHubWebhookEvent, TaskRunContext, AnyWebhookEndpoint, InferWebhookEndpointEvent, WebhookEndpoint, WebhookEndpointContext, TaskOptions } from "@trigger.dev/core/v3";
+import { cancelWebhookWaiter, createWebhookWaiter, waitForWebhookWaiter } from "./webhookWaiters.js";
+import { type Task } from "./shared.js";
+import { type WebhookProviderId } from "@trigger.dev/core/webhooks";
 /**
  * The type of error thrown when a webhook fails to parse or verify
  */
@@ -14,6 +18,159 @@ type ConstructEventOptions = {
     /** Signature header as string, Buffer, or string array */
     header: string | Buffer | Array<string>;
 };
+/**
+ * The verifier configs a hosted endpoint can enforce. A `url-secret` placed in the path is excluded:
+ * the hosted ingress URL is fixed per endpoint, so there is no path segment for the caller to choose,
+ * and the server refuses such a declaration at deploy time. Use `placement: "query"` instead.
+ */
+export type HostedWebhookVerifierConfig = Exclude<WebhookVerifierConfig, WebhookUrlSecretConfig> | (Omit<WebhookUrlSecretConfig, "placement"> & {
+    placement: "query";
+});
+export declare const webhookSources: {
+    readonly custom: <T = unknown>(config: HostedWebhookVerifierConfig, options?: {
+        /** Instructions for an AI agent registering an endpoint on this source with the provider. */
+        setupPrompt?: string;
+        /**
+         * How the endpoint answers the provider. `{ acceptedBody: "empty" }` acknowledges with an empty
+         * 200, for providers that show the response to a user (Slack slash commands).
+         */
+        response?: WebhookResponseConfig;
+    }) => WebhookSource<T>;
+    readonly stripe: <TEvent = StripeWebhookEvent>(opts?: {
+        toleranceSeconds?: number;
+    }) => WebhookSource<TEvent>;
+    readonly github: <TEvent = GitHubWebhookEvent>() => WebhookSource<TEvent>;
+    readonly svix: <T = unknown>() => WebhookSource<T>;
+    readonly standardWebhooks: <T = unknown>() => WebhookSource<T>;
+    readonly square: <T = unknown>() => WebhookSource<T>;
+    /**
+     * Discord: asymmetric Ed25519 over `{timestamp}{body}`. The "secret" stored on the endpoint is the
+     * application PUBLIC KEY (hex by default); there is no shared secret. Discord's response contract
+     * is declared as data on the artifact: the `{ type: 0 }` PING sent when the URL is saved is answered
+     * with a bodiless 204 and never recorded, accepted events are acknowledged with 204, and a bad
+     * signature gets 401.
+     */
+    readonly discord: <T = unknown>(opts?: {
+        publicKeyEncoding?: "raw-hex" | "pem";
+    }) => WebhookSource<T>;
+    /**
+     * Per-provider producers over shared presets. Each is a thin wrapper: same verifier config as the
+     * preset it references, differing only in `provider` (routing + picker identity) and who provisions
+     * the secret. Pass the provider's own published type for full typing, e.g. clerk<WebhookEvent>().
+     */
+    readonly clerk: <T = unknown>() => WebhookSource<T>;
+    readonly resend: <T = unknown>() => WebhookSource<T>;
+    readonly openai: <T = unknown>() => WebhookSource<T>;
+    readonly replicate: <T = unknown>() => WebhookSource<T>;
+    readonly recallai: <T = unknown>() => WebhookSource<T>;
+    readonly brex: <T = unknown>() => WebhookSource<T>;
+    readonly composio: <T = unknown>() => WebhookSource<T>;
+    readonly gitlab: <T = unknown>() => WebhookSource<T>;
+    /**
+     * WhatsApp Cloud API (Meta): `X-Hub-Signature-256` HMAC over the raw body, keyed by the App Secret,
+     * which Meta issues and you paste in as the endpoint's signing secret (it cannot be generated here).
+     * Meta verifies the callback URL with a GET carrying `hub.mode`, `hub.verify_token` and
+     * `hub.challenge`; the endpoint answers it when the token equals the verify token generated in
+     * the endpoint's Connect panel, which you paste into Meta's Verify Token field.
+     */
+    readonly whatsapp: <T = unknown>() => WebhookSource<T>;
+};
+type CamelCase<S extends string> = S extends `${infer Head}-${infer Tail}` ? `${Head}${Capitalize<CamelCase<Tail>>}` : S;
+/**
+ * Per-provider producers generated from the core config table (kind "config"). Each carries the
+ * provider's own HMAC verifier config and stays in lockstep with the round-trip-tested configs.
+ * The method is the provider id in camel case (`cal-com` is `webhooks.calCom()`); the emitted
+ * `provider` keeps the id itself.
+ */
+export type ProviderProducers = {
+    [K in Exclude<WebhookProviderId, "zoom"> as CamelCase<K>]: <TEvent = unknown>() => WebhookSource<TEvent>;
+};
+export declare const providerProducers: Omit<ProviderProducers, "slack">;
+export type WebhookEndpointOptions<TIdentifier extends string, TSource extends AnyWebhookSource> = {
+    /** The endpoint id. Subscribers reference the endpoint, and it names the endpoint's URL. */
+    id: TIdentifier;
+    /** The provider source: how deliveries are verified and who issues the signing secret. */
+    source: TSource;
+    description?: string;
+    /** Arbitrary metadata, passed to every subscriber and waiter as `endpoint.metadata`. */
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Declare a webhook endpoint: one URL you register with the provider. Subscribe to it with
+ * `webhook({ endpoint })`, `chat.event({ endpoint })` or a channel connector, and wait on it with
+ * `webhooks.waiter.create(endpoint, ...)`. An endpoint with no subscribers still gets a URL.
+ */
+export declare function defineWebhookEndpoint<TIdentifier extends string, TSource extends AnyWebhookSource>(options: WebhookEndpointOptions<TIdentifier, TSource>): WebhookEndpoint<InferWebhookEvent<TSource>> & {
+    id: TIdentifier;
+};
+export type WebhookOnEventParams<TEvent> = {
+    /** The verified event body, typed by the endpoint's source. */
+    event: TEvent;
+    /** The inbound request headers (case-insensitive, Web `Headers`). e.g. headers.get("x-github-event"). */
+    headers: Headers;
+    /** The endpoint the delivery arrived on. Unset when the task is triggered by hand without one. */
+    endpoint?: WebhookEndpointContext;
+    ctx: TaskRunContext;
+};
+/**
+ * The `task()` options a webhook task also takes: `queue`, `concurrency`, `machine`, `retry`,
+ * `maxDuration`, `ttl` and the lifecycle hooks. e.g. `queue: { concurrencyLimit: 1 }` handles one
+ * delivery at a time.
+ */
+export type WebhookTaskOptions<TIdentifier extends string, TEvent> = Omit<TaskOptions<TIdentifier, WebhookTaskPayload<TEvent>, void>, "id" | "run" | "jsonSchema" | "triggerSource" | "agentConfig">;
+export type WebhookOptions<TIdentifier extends string, TEndpoint extends AnyWebhookEndpoint, TEvent = InferWebhookEndpointEvent<TEndpoint>> = WebhookTaskOptions<TIdentifier, TEvent> & {
+    id: TIdentifier;
+    /** The endpoint this task subscribes to. */
+    endpoint: TEndpoint;
+    /**
+     * Optional server-side filter (a type-safe string DSL checked against the event shape). A delivery
+     * this subscriber's filter rejects is still recorded, and other subscribers on the endpoint still
+     * get it. e.g. `"event.action == 'created' && event.repository.private == false"`.
+     */
+    filter?: string;
+    /** Gets the event narrowed by the filter's `event.<field> == '<value>'` clauses. */
+    onEvent: (params: WebhookOnEventParams<TEvent>) => Promise<void> | void;
+};
+/**
+ * What a webhook task runs on: the verified event, the delivery headers and the endpoint. The hosted
+ * ingress sends it for every delivery; triggering the handle by hand (`myWebhook.trigger({ event })`,
+ * a replay, a test) sends the same shape, so `onEvent` sees the event either way.
+ */
+export type WebhookTaskPayload<TEvent> = {
+    event: TEvent;
+    headers?: Record<string, string>;
+    endpoint?: WebhookEndpointContext;
+};
+export type WebhookHandle<TIdentifier extends string, TEvent> = Task<TIdentifier, WebhookTaskPayload<TEvent>, void>;
+export declare function webhook<TIdentifier extends string, TEndpoint extends AnyWebhookEndpoint, const TFilter extends string = string>(options: WebhookOptions<TIdentifier, TEndpoint, NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>> & {
+    filter?: ValidateWebhookFilter<InferWebhookEndpointEvent<TEndpoint>, TFilter>;
+}): WebhookHandle<TIdentifier, NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>>;
+export declare function chatEvent<TEndpoint extends AnyWebhookEndpoint, const TId extends string = string, const TKey extends string = string, const TType extends string = TId, const TFilter extends string = string>(options: {
+    id: TId;
+    /** The endpoint this event subscribes to. */
+    endpoint: TEndpoint;
+    /**
+     * The session each delivery goes to, as a template: `{event.x}` reads the event, `{header.x}` a
+     * header and `{webhook.x}` the endpoint, and `{a || b}` falls back to `b` when `a` is empty. e.g.
+     * `"{webhook.externalRef}:{event.data.object.customer}"`.
+     */
+    key: ValidatedWebhookKey<NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>, TKey>;
+    /** The `action.type` the handler reads. Optional; defaults to `id`. */
+    type?: TType;
+    /**
+     * Optional server-side filter (same type-safe DSL as `webhook()`); a non-match is recorded FILTERED
+     * and not routed. Narrows the action's `event` like `webhook()`'s `onEvent`.
+     */
+    filter?: ValidateWebhookFilter<InferWebhookEndpointEvent<TEndpoint>, TFilter>;
+}): ChatEvent<TType, NarrowWebhookEvent<InferWebhookEndpointEvent<TEndpoint>, TFilter>>;
+export type { ChatEvent, AnyChatEvent, ChatEventAction, ChatEventActions, WebhookKeyMeta, } from "@trigger.dev/core/v3";
+/**
+ * Compiles a key template to its stored form. Each placeholder names its namespace the way a filter
+ * path does: `{event.x}` reads the event body (stored as `{body.x}`), `{header.x}` a header and
+ * `{webhook.x}` the endpoint. A placeholder without one of those namespaces throws.
+ */
+export declare function normalizeKeyString(key: string): string;
+export type { CreateWebhookEndpointParams } from "@trigger.dev/core/v3";
 /**
  * Interface describing the webhook utilities
  */
@@ -39,9 +196,34 @@ interface Webhooks {
     constructEvent(request: ConstructEventOptions | Request, secret: string): Promise<Webhook>;
     /** Header name used for webhook signatures */
     SIGNATURE_HEADER_NAME: string;
+    custom: typeof webhookSources.custom;
+    stripe: typeof webhookSources.stripe;
+    github: typeof webhookSources.github;
+    svix: typeof webhookSources.svix;
+    standardWebhooks: typeof webhookSources.standardWebhooks;
+    square: typeof webhookSources.square;
+    discord: typeof webhookSources.discord;
+    clerk: typeof webhookSources.clerk;
+    resend: typeof webhookSources.resend;
+    openai: typeof webhookSources.openai;
+    replicate: typeof webhookSources.replicate;
+    recallai: typeof webhookSources.recallai;
+    brex: typeof webhookSources.brex;
+    composio: typeof webhookSources.composio;
+    gitlab: typeof webhookSources.gitlab;
+    whatsapp: typeof webhookSources.whatsapp;
+    /** Declare the URLs providers deliver to. */
+    endpoint: {
+        define: typeof defineWebhookEndpoint;
+    };
+    /** Suspend a run until a matching webhook arrives. */
+    waiter: {
+        create: typeof createWebhookWaiter;
+        wait: typeof waitForWebhookWaiter;
+        cancel: typeof cancelWebhookWaiter;
+    };
 }
 /**
  * Webhook utilities for handling incoming webhook requests
  */
-export declare const webhooks: Webhooks;
-export {};
+export declare const webhooks: Webhooks & Omit<ProviderProducers, "slack">;

package/dist/esm/v3/webhooks.js

@@ -1,5 +1,8 @@
-import { Webhook } from "@trigger.dev/core/v3";
+import { Webhook, resourceCatalog } from "@trigger.dev/core/v3";
 import { subtle } from "../imports/uncrypto.js";
+import { cancelWebhookWaiter, createWebhookWaiter, waitForWebhookWaiter, } from "./webhookWaiters.js";
+import { createTask } from "./shared.js";
+import { discordVerifierConfig, githubVerifierConfig, squareVerifierConfig, standardWebhooksVerifierConfig, stripeVerifierConfig, svixVerifierConfig, webhookProviderConfigs, webhookSetupPrompts, } from "@trigger.dev/core/webhooks";
 /**
  * The type of error thrown when a webhook fails to parse or verify
  */
@@ -11,12 +14,327 @@ export class WebhookError extends Error {
 }
 /** Header name used for webhook signatures */
 const SIGNATURE_HEADER_NAME = "x-trigger-signature-hmacsha256";
+// ── Source producers (presets carry the event type) ──
+export const webhookSources = {
+    custom(config, options) {
+        if (config.scheme === "url-secret" && config.placement === "path") {
+            throw new Error('webhooks.custom(): url-secret verification cannot use placement "path" on the hosted ingress URL. Use placement "query" or a header-based scheme.');
+        }
+        // Roll-your-own webhooks: you control both ends, so offer paste AND generate.
+        return {
+            provider: "custom",
+            verifier: {
+                kind: "config",
+                config,
+                ...(options?.response ? { response: options.response } : {}),
+            },
+            secretProvisioning: "either",
+            ...(options?.setupPrompt ? { setupPrompt: options.setupPrompt } : {}),
+        };
+    },
+    // Stripe: `Stripe-Signature: t=…,v1=…` (comma-kv), signed `{t}.{body}`, hex.
+    // Defaults to a minimal event shape; pass the official type for full typing: stripe<Stripe.Event>().
+    stripe(opts) {
+        return {
+            provider: "stripe",
+            verifier: { kind: "preset", preset: "stripe", config: stripeVerifierConfig(opts) },
+            secretProvisioning: "provider",
+        };
+    },
+    // GitHub: `X-Hub-Signature-256: sha256=<hex>` (prefixed), signed raw body.
+    // Defaults to an open shape; pass your event type for full typing: github<MyPushEvent>().
+    github() {
+        return {
+            provider: "github",
+            verifier: { kind: "preset", preset: "github", config: githubVerifierConfig() },
+            secretProvisioning: "integrator",
+        };
+    },
+    // Svix family (Svix, Clerk, Resend): `svix-signature: v1,<b64> v1,<b64>` (space-list),
+    // signed `{id}.{timestamp}.{body}`, base64; the `whsec_` secret is base64-decoded. Providers that
+    // send the spec's `webhook-*` header names instead use `standardWebhooks()`.
+    svix() {
+        return {
+            provider: "svix",
+            verifier: { kind: "preset", preset: "svix", config: svixVerifierConfig() },
+            secretProvisioning: "provider",
+        };
+    },
+    // Standard Webhooks (Composio, and any provider implementing the spec directly): the Svix scheme under
+    // the spec's `webhook-id` / `webhook-timestamp` / `webhook-signature` header names.
+    standardWebhooks() {
+        return {
+            provider: "standard-webhooks",
+            verifier: {
+                kind: "preset",
+                preset: "standard-webhooks",
+                config: standardWebhooksVerifierConfig(),
+            },
+            secretProvisioning: "provider",
+        };
+    },
+    // Square: bare base64 signature over `{notificationURL}{body}` (URL template var, no separator).
+    square() {
+        return {
+            provider: "square",
+            verifier: { kind: "preset", preset: "square", config: squareVerifierConfig() },
+            secretProvisioning: "provider",
+        };
+    },
+    /**
+     * Discord: asymmetric Ed25519 over `{timestamp}{body}`. The "secret" stored on the endpoint is the
+     * application PUBLIC KEY (hex by default); there is no shared secret. Discord's response contract
+     * is declared as data on the artifact: the `{ type: 0 }` PING sent when the URL is saved is answered
+     * with a bodiless 204 and never recorded, accepted events are acknowledged with 204, and a bad
+     * signature gets 401.
+     */
+    discord(opts = {}) {
+        return {
+            provider: "discord",
+            verifier: {
+                kind: "preset",
+                preset: "discord",
+                config: discordVerifierConfig(opts),
+                handshake: { matchPath: "type", matchValue: "0", respondStatus: 204 },
+                response: { acceptedStatus: 204, rejectedStatus: 401 },
+            },
+            secretProvisioning: "provider",
+        };
+    },
+    /**
+     * Per-provider producers over shared presets. Each is a thin wrapper: same verifier config as the
+     * preset it references, differing only in `provider` (routing + picker identity) and who provisions
+     * the secret. Pass the provider's own published type for full typing, e.g. clerk<WebhookEvent>().
+     */
+    clerk() {
+        return {
+            provider: "clerk",
+            verifier: { kind: "preset", preset: "svix", config: svixVerifierConfig() },
+            secretProvisioning: "provider",
+        };
+    },
+    resend() {
+        return {
+            provider: "resend",
+            verifier: { kind: "preset", preset: "svix", config: svixVerifierConfig() },
+            secretProvisioning: "provider",
+        };
+    },
+    openai() {
+        return {
+            provider: "openai",
+            verifier: {
+                kind: "preset",
+                preset: "standard-webhooks",
+                config: standardWebhooksVerifierConfig(),
+            },
+            secretProvisioning: "provider",
+        };
+    },
+    replicate() {
+        return {
+            provider: "replicate",
+            verifier: {
+                kind: "preset",
+                preset: "standard-webhooks",
+                config: standardWebhooksVerifierConfig(),
+            },
+            secretProvisioning: "provider",
+        };
+    },
+    recallai() {
+        return {
+            provider: "recall-ai",
+            verifier: {
+                kind: "preset",
+                preset: "standard-webhooks",
+                config: standardWebhooksVerifierConfig(),
+            },
+            secretProvisioning: "provider",
+        };
+    },
+    brex() {
+        return {
+            provider: "brex",
+            verifier: { kind: "preset", preset: "svix", config: svixVerifierConfig() },
+            secretProvisioning: "provider",
+        };
+    },
+    composio() {
+        return {
+            provider: "composio",
+            verifier: {
+                kind: "preset",
+                preset: "standard-webhooks",
+                config: standardWebhooksVerifierConfig(),
+            },
+            secretProvisioning: "provider",
+        };
+    },
+    gitlab() {
+        return {
+            provider: "gitlab",
+            verifier: {
+                kind: "config",
+                config: { scheme: "shared-secret", placement: "header", fieldName: "x-gitlab-token" },
+            },
+            secretProvisioning: "integrator",
+        };
+    },
+    /**
+     * WhatsApp Cloud API (Meta): `X-Hub-Signature-256` HMAC over the raw body, keyed by the App Secret,
+     * which Meta issues and you paste in as the endpoint's signing secret (it cannot be generated here).
+     * Meta verifies the callback URL with a GET carrying `hub.mode`, `hub.verify_token` and
+     * `hub.challenge`; the endpoint answers it when the token equals the verify token generated in
+     * the endpoint's Connect panel, which you paste into Meta's Verify Token field.
+     */
+    whatsapp() {
+        return {
+            provider: "whatsapp",
+            verifier: {
+                kind: "preset",
+                preset: "github",
+                config: githubVerifierConfig(),
+                getHandshake: {
+                    matchParam: "hub.mode",
+                    matchValue: "subscribe",
+                    tokenParam: "hub.verify_token",
+                    challengeParam: "hub.challenge",
+                },
+            },
+            secretProvisioning: "provider",
+        };
+    },
+};
+function producerName(provider) {
+    return provider.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+export const providerProducers = Object.fromEntries(Object.entries(webhookProviderConfigs)
+    // Zoom needs a computed URL-validation response that the hosted ingress does not support yet.
+    .filter(([provider]) => provider !== "slack" && provider !== "zoom")
+    .map(([provider, entry]) => [
+    producerName(provider),
+    () => {
+        const setupPrompt = webhookSetupPrompts[provider];
+        return {
+            provider,
+            verifier: { kind: "config", config: entry.config() },
+            secretProvisioning: entry.secretProvisioning,
+            ...(setupPrompt ? { setupPrompt } : {}),
+        };
+    },
+]));
+/**
+ * Declare a webhook endpoint: one URL you register with the provider. Subscribe to it with
+ * `webhook({ endpoint })`, `chat.event({ endpoint })` or a channel connector, and wait on it with
+ * `webhooks.waiter.create(endpoint, ...)`. An endpoint with no subscribers still gets a URL.
+ */
+export function defineWebhookEndpoint(options) {
+    const { id, source, description, metadata } = options;
+    if (id.startsWith("wh_")) {
+        throw new Error(`webhooks.endpoint.define("${id}"): an endpoint id can't start with "wh_"; that prefix is reserved for generated endpoint ids.`);
+    }
+    const setupPrompt = source.setupPrompt ??
+        (source.verifier.kind === "preset"
+            ? webhookSetupPrompts[source.verifier.preset]
+            : undefined);
+    resourceCatalog.registerWebhookEndpointMetadata({
+        id,
+        source: source.provider,
+        verifierArtifact: source.verifier,
+        ...(description ? { description } : {}),
+        ...(source.secretProvisioning ? { secretProvisioning: source.secretProvisioning } : {}),
+        ...(setupPrompt ? { setupPrompt } : {}),
+        ...(metadata ? { metadata } : {}),
+    });
+    return { id, source: source.provider };
+}
+export function webhook(options) {
+    const { id, endpoint, onEvent, filter, ...taskOptions } = options;
+    if (!endpoint?.id) {
+        throw new Error(`webhook("${id}"): an endpoint is required. Declare one with webhooks.endpoint.define() and pass it as { endpoint }.`);
+    }
+    const task = createTask({
+        ...taskOptions,
+        id,
+        triggerSource: "webhook",
+        run: async (payload, runOptions) => {
+            await onEvent({
+                event: payload.event,
+                headers: new Headers(payload.headers ?? {}),
+                endpoint: payload.endpoint,
+                ctx: runOptions.ctx,
+            });
+        },
+    });
+    resourceCatalog.registerWebhookSubscriber({
+        endpointId: endpoint.id,
+        target: { type: "task", id, taskId: id, ...(filter ? { filter } : {}) },
+    });
+    return task;
+}
+// ── chat.event(): a session subscriber an agent claims via chat.agent({ events }). No handler. ──
+// Carries the endpoint, a validated string `key`, and a `type` discriminant. The `key` validates
+// against the event/header/webhook namespaces, like a filter path, and compiles to the stored
+// {body.x} wire template.
+export function chatEvent(options) {
+    const { id, endpoint, key, type, filter } = options;
+    if (!endpoint?.id) {
+        throw new Error(`chat.event("${id}"): an endpoint is required. Declare one with webhooks.endpoint.define() and pass it as { endpoint }.`);
+    }
+    // Record the descriptor as declared so the indexer can flag it if no agent ever claims it.
+    resourceCatalog.registerDeclaredSessionWebhook(id);
+    return {
+        id,
+        type: type ?? id,
+        key: normalizeKeyString(key),
+        endpointId: endpoint.id,
+        source: endpoint.source,
+        filter,
+    };
+}
+/**
+ * Compiles a key template to its stored form. Each placeholder names its namespace the way a filter
+ * path does: `{event.x}` reads the event body (stored as `{body.x}`), `{header.x}` a header and
+ * `{webhook.x}` the endpoint. A placeholder without one of those namespaces throws.
+ */
+export function normalizeKeyString(key) {
+    const namespaceAlternative = (alternative) => {
+        const trimmed = alternative.trim();
+        if (trimmed.startsWith("event."))
+            return `body.${trimmed.slice("event.".length)}`;
+        if (trimmed.startsWith("webhook.") || trimmed.startsWith("header."))
+            return trimmed;
+        const path = trimmed.startsWith("body.") ? trimmed.slice("body.".length) : trimmed;
+        throw new Error(`Invalid key "${key}": "{${trimmed}}" needs a namespace. Use {event.${path}} for the event body, {header.<name>} or {webhook.<field>}.`);
+    };
+    return key.replace(/\{([^{}]+)\}/g, (_match, path) => `{${path.split("||").map(namespaceAlternative).join(" || ")}}`);
+}
 /**
  * Webhook utilities for handling incoming webhook requests
  */
 export const webhooks = {
+    ...providerProducers,
     constructEvent,
     SIGNATURE_HEADER_NAME,
+    custom: webhookSources.custom,
+    stripe: webhookSources.stripe,
+    github: webhookSources.github,
+    svix: webhookSources.svix,
+    standardWebhooks: webhookSources.standardWebhooks,
+    square: webhookSources.square,
+    discord: webhookSources.discord,
+    clerk: webhookSources.clerk,
+    resend: webhookSources.resend,
+    openai: webhookSources.openai,
+    replicate: webhookSources.replicate,
+    recallai: webhookSources.recallai,
+    brex: webhookSources.brex,
+    composio: webhookSources.composio,
+    gitlab: webhookSources.gitlab,
+    whatsapp: webhookSources.whatsapp,
+    endpoint: { define: defineWebhookEndpoint },
+    waiter: { create: createWebhookWaiter, wait: waitForWebhookWaiter, cancel: cancelWebhookWaiter },
 };
 async function constructEvent(request, secret) {
     let payload;

package/dist/esm/v3/webhooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../../../src/v3/webhooks.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../../../src/v3/webhooks.ts"],"names":[],"mappings":"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"}

package/dist/esm/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "4.7.4";
+export const VERSION = "4.8.0-webhooks.20261020092920";
 //# sourceMappingURL=version.js.map

package/docs/ai-chat/actions.mdx

@@ -73,11 +73,16 @@ onAction: async ({ action }) => {
       chat.history.slice(0, -1);
       chat.inject([{ role: "system", content: "Answer formally this time." }]);
       return chat.turn(); // with a one-shot instruction
+
+    case "ask":
+      return chat.turn(action.question); // answer a new user message
   }
 }
 ```
 
-`run()` receives the edited history with no incoming user message, the same shape as a `regenerate-message` turn, and its `trigger` is `"action-turn"`, so a `run()` that returns early on `"action"` (the pre-May behaviour, when actions invoked `run()` directly) still answers. Returning anything other than `chat.turn()` or nothing is an error; a response can no longer be returned from `onAction` directly.
+`chat.turn(message)` appends `message` (a string, or a `UIMessage`) to the history as a user message after the edit, and the turn answers it. That is how a button click becomes a question, such as a follow-up suggestion in [Slack](/webhooks/slack#buttons-that-send-the-agent-an-action).
+
+Without a message, `run()` receives the edited history with no incoming user message, the same shape as a `regenerate-message` turn, and its `trigger` is `"action-turn"`, so a `run()` that returns early on `"action"` (the pre-May behaviour, when actions invoked `run()` directly) still answers. Returning anything other than `chat.turn()` or nothing is an error; a response can no longer be returned from `onAction` directly.
 
 ### Actions and persistence
 

package/docs/ai-chat/backend.mdx

@@ -4,6 +4,8 @@ sidebarTitle: "Backend"
 description: "Three approaches to building your chat backend — chat.agent(), session iterator, or raw task primitives."
 ---
 
+import WebhooksBetaNote from "/snippets/webhooks-beta-note.mdx";
+
 There are three abstraction levels for a chat backend. All three speak the same wire protocol, so the [frontend transport](/ai-chat/frontend) works unchanged whichever you pick.
 
 | Capability                            | `chat.agent()` | `chat.createSession()`                                        | Raw primitives |
@@ -497,6 +499,44 @@ Custom actions let the frontend send structured commands (undo, rollback, edit,
 
 See [Actions](/ai-chat/actions).
 
+### Webhook events and channels
+
+<WebhooksBetaNote />
+
+Two `chat.agent()` options wire an agent to verified inbound webhooks. `events` claims [`chat.event(...)`](/webhooks/session-routing) descriptors: each verified delivery is routed to this agent's session and arrives at `onAction` as an action (not a turn), so [session routing](/webhooks/session-routing) decides which conversation it lands on. `channels` claims channel connectors that turn an external chat surface into a frontend for the agent: an inbound message runs as a turn through `run()` and the reply is posted back. `slack()` ships in `@trigger.dev/slack`, and `chat.channels.custom(...)` builds a connector for any endpoint without a preset.
+
+```ts
+import { webhooks } from "@trigger.dev/sdk";
+import { chat } from "@trigger.dev/sdk/ai";
+import { slack, webhookSource } from "@trigger.dev/slack";
+
+const slackEvents = webhooks.endpoint.define({ id: "slack", source: webhookSource() });
+const stripe = webhooks.endpoint.define({ id: "stripe", source: webhooks.stripe() });
+
+export const orderEvents = chat.event({
+  id: "order-events",
+  endpoint: stripe,
+  key: "{event.data.object.customer}",
+  // invoices always carry a customer; events without one would have no session to go to
+  filter: "event.type startsWith 'invoice.'",
+  type: "order.event",
+});
+
+export const myChat = chat.agent({
+  id: "my-chat",
+  events: [orderEvents],
+  channels: [slack({ id: "support-slack", endpoint: slackEvents, token: process.env.SLACK_BOT_TOKEN! })],
+  onAction: async ({ action }) => {
+    // A verified order-events delivery arrives here as an action.
+  },
+  run: async (payload) => {
+    // Inbound Slack messages run here as normal turns.
+  },
+});
+```
+
+See [session routing](/webhooks/session-routing) and [channels](/webhooks/channels). For the interactive approvals layer, where a turn pauses on a human decision (buttons in the thread) and resumes on the click, see [human-in-the-loop](/webhooks/human-in-the-loop).
+
 ### Chat history
 
 Imperative API for reading and modifying the accumulated message history. Works from any hook (`onAction`, `onTurnStart`, `onBeforeTurnComplete`, `onTurnComplete`, `hydrateMessages`) or from `run()` and AI SDK tools.