From 716bafe75f2eb6b7cdcca213ca656c31140c2800 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 12:42:18 +0000 Subject: [PATCH 01/37] docs(webhooks): restructure webhook docs around providers - Add a page for each built-in provider source under Webhooks > Providers, with an index of every source and its credential - Add a quick start, a custom providers page split out of sources, and a page on using your own handler - Fold the public beta page into the overview - Rename the Next.js and Remix webhook guides to custom handler guides, move them under Frameworks, and point readers to hosted endpoints - Remove the Guides > Webhooks group; redirect the old overview, Stripe and Hookdeck guides to the new pages --- docs/docs.json | 92 +++++++++-- docs/guides/examples/hookdeck-webhook.mdx | 102 ------------ docs/guides/examples/stripe-webhook.mdx | 151 ------------------ docs/guides/frameworks/nextjs-webhooks.mdx | 11 +- docs/guides/frameworks/remix-webhooks.mdx | 11 +- ...abase-edge-functions-database-webhooks.mdx | 5 + .../frameworks/webhooks-guides-overview.mdx | 45 ------ docs/guides/introduction.mdx | 7 +- docs/snippets/examples-cards.mdx | 6 +- docs/webhooks/connect.mdx | 2 +- docs/webhooks/custom-providers.mdx | 85 ++++++++++ docs/webhooks/deliveries.mdx | 2 +- docs/webhooks/overview.mdx | 22 ++- docs/webhooks/own-handler.mdx | 58 +++++++ docs/webhooks/providers.mdx | 58 +++++++ docs/webhooks/providers/attio.mdx | 38 +++++ docs/webhooks/providers/autumn.mdx | 41 +++++ docs/webhooks/providers/brex.mdx | 41 +++++ docs/webhooks/providers/cal-com.mdx | 41 +++++ docs/webhooks/providers/calendly.mdx | 41 +++++ docs/webhooks/providers/clerk.mdx | 40 +++++ docs/webhooks/providers/composio.mdx | 40 +++++ docs/webhooks/providers/discord.mdx | 45 ++++++ docs/webhooks/providers/docusign.mdx | 41 +++++ docs/webhooks/providers/elevenlabs.mdx | 41 +++++ docs/webhooks/providers/firecrawl.mdx | 54 +++++++ docs/webhooks/providers/github.mdx | 46 ++++++ docs/webhooks/providers/gitlab.mdx | 41 +++++ docs/webhooks/providers/granola.mdx | 44 +++++ docs/webhooks/providers/hookdeck.mdx | 69 ++++++++ docs/webhooks/providers/infisical.mdx | 41 +++++ docs/webhooks/providers/intercom.mdx | 41 +++++ docs/webhooks/providers/jira.mdx | 41 +++++ docs/webhooks/providers/langfuse.mdx | 40 +++++ docs/webhooks/providers/linear.mdx | 45 ++++++ docs/webhooks/providers/loops.mdx | 41 +++++ docs/webhooks/providers/metronome.mdx | 42 +++++ docs/webhooks/providers/mux.mdx | 40 +++++ docs/webhooks/providers/notion.mdx | 40 +++++ docs/webhooks/providers/openai.mdx | 40 +++++ docs/webhooks/providers/pagerduty.mdx | 40 +++++ docs/webhooks/providers/plain.mdx | 41 +++++ docs/webhooks/providers/planetscale.mdx | 41 +++++ docs/webhooks/providers/recall-ai.mdx | 41 +++++ docs/webhooks/providers/replicate.mdx | 41 +++++ docs/webhooks/providers/resend.mdx | 44 +++++ docs/webhooks/providers/retell.mdx | 41 +++++ docs/webhooks/providers/sentry.mdx | 41 +++++ docs/webhooks/providers/shopify.mdx | 49 ++++++ docs/webhooks/providers/slack.mdx | 47 ++++++ docs/webhooks/providers/square.mdx | 40 +++++ docs/webhooks/providers/stripe.mdx | 61 +++++++ docs/webhooks/providers/supabase.mdx | 41 +++++ docs/webhooks/providers/tailscale.mdx | 44 +++++ docs/webhooks/providers/typeform.mdx | 41 +++++ docs/webhooks/providers/vapi.mdx | 41 +++++ docs/webhooks/providers/vercel.mdx | 40 +++++ docs/webhooks/providers/whatsapp.mdx | 39 +++++ docs/webhooks/providers/workos.mdx | 41 +++++ docs/webhooks/providers/zendesk.mdx | 41 +++++ docs/webhooks/providers/zoom.mdx | 41 +++++ docs/webhooks/public-beta.mdx | 70 -------- docs/webhooks/quick-start.mdx | 127 +++++++++++++++ docs/webhooks/sources.mdx | 131 +-------------- 64 files changed, 2427 insertions(+), 528 deletions(-) delete mode 100644 docs/guides/examples/hookdeck-webhook.mdx delete mode 100644 docs/guides/examples/stripe-webhook.mdx delete mode 100644 docs/guides/frameworks/webhooks-guides-overview.mdx create mode 100644 docs/webhooks/custom-providers.mdx create mode 100644 docs/webhooks/own-handler.mdx create mode 100644 docs/webhooks/providers.mdx create mode 100644 docs/webhooks/providers/attio.mdx create mode 100644 docs/webhooks/providers/autumn.mdx create mode 100644 docs/webhooks/providers/brex.mdx create mode 100644 docs/webhooks/providers/cal-com.mdx create mode 100644 docs/webhooks/providers/calendly.mdx create mode 100644 docs/webhooks/providers/clerk.mdx create mode 100644 docs/webhooks/providers/composio.mdx create mode 100644 docs/webhooks/providers/discord.mdx create mode 100644 docs/webhooks/providers/docusign.mdx create mode 100644 docs/webhooks/providers/elevenlabs.mdx create mode 100644 docs/webhooks/providers/firecrawl.mdx create mode 100644 docs/webhooks/providers/github.mdx create mode 100644 docs/webhooks/providers/gitlab.mdx create mode 100644 docs/webhooks/providers/granola.mdx create mode 100644 docs/webhooks/providers/hookdeck.mdx create mode 100644 docs/webhooks/providers/infisical.mdx create mode 100644 docs/webhooks/providers/intercom.mdx create mode 100644 docs/webhooks/providers/jira.mdx create mode 100644 docs/webhooks/providers/langfuse.mdx create mode 100644 docs/webhooks/providers/linear.mdx create mode 100644 docs/webhooks/providers/loops.mdx create mode 100644 docs/webhooks/providers/metronome.mdx create mode 100644 docs/webhooks/providers/mux.mdx create mode 100644 docs/webhooks/providers/notion.mdx create mode 100644 docs/webhooks/providers/openai.mdx create mode 100644 docs/webhooks/providers/pagerduty.mdx create mode 100644 docs/webhooks/providers/plain.mdx create mode 100644 docs/webhooks/providers/planetscale.mdx create mode 100644 docs/webhooks/providers/recall-ai.mdx create mode 100644 docs/webhooks/providers/replicate.mdx create mode 100644 docs/webhooks/providers/resend.mdx create mode 100644 docs/webhooks/providers/retell.mdx create mode 100644 docs/webhooks/providers/sentry.mdx create mode 100644 docs/webhooks/providers/shopify.mdx create mode 100644 docs/webhooks/providers/slack.mdx create mode 100644 docs/webhooks/providers/square.mdx create mode 100644 docs/webhooks/providers/stripe.mdx create mode 100644 docs/webhooks/providers/supabase.mdx create mode 100644 docs/webhooks/providers/tailscale.mdx create mode 100644 docs/webhooks/providers/typeform.mdx create mode 100644 docs/webhooks/providers/vapi.mdx create mode 100644 docs/webhooks/providers/vercel.mdx create mode 100644 docs/webhooks/providers/whatsapp.mdx create mode 100644 docs/webhooks/providers/workos.mdx create mode 100644 docs/webhooks/providers/zendesk.mdx create mode 100644 docs/webhooks/providers/zoom.mdx delete mode 100644 docs/webhooks/public-beta.mdx create mode 100644 docs/webhooks/quick-start.mdx diff --git a/docs/docs.json b/docs/docs.json index f4d8ebc5fd0..69c972550b3 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -171,9 +171,62 @@ "group": "Webhooks", "pages": [ "webhooks/overview", - "webhooks/public-beta", + "webhooks/quick-start", "webhooks/sources", "webhooks/connect", + { + "group": "Providers", + "pages": [ + "webhooks/providers", + "webhooks/providers/attio", + "webhooks/providers/autumn", + "webhooks/providers/brex", + "webhooks/providers/cal-com", + "webhooks/providers/calendly", + "webhooks/providers/clerk", + "webhooks/providers/composio", + "webhooks/providers/discord", + "webhooks/providers/docusign", + "webhooks/providers/elevenlabs", + "webhooks/providers/firecrawl", + "webhooks/providers/github", + "webhooks/providers/gitlab", + "webhooks/providers/granola", + "webhooks/providers/hookdeck", + "webhooks/providers/infisical", + "webhooks/providers/intercom", + "webhooks/providers/jira", + "webhooks/providers/langfuse", + "webhooks/providers/linear", + "webhooks/providers/loops", + "webhooks/providers/metronome", + "webhooks/providers/mux", + "webhooks/providers/notion", + "webhooks/providers/openai", + "webhooks/providers/pagerduty", + "webhooks/providers/plain", + "webhooks/providers/planetscale", + "webhooks/providers/recall-ai", + "webhooks/providers/replicate", + "webhooks/providers/resend", + "webhooks/providers/retell", + "webhooks/providers/sentry", + "webhooks/providers/shopify", + "webhooks/providers/slack", + "webhooks/providers/square", + "webhooks/providers/stripe", + "webhooks/providers/supabase", + "webhooks/providers/tailscale", + "webhooks/providers/typeform", + "webhooks/providers/vapi", + "webhooks/providers/vercel", + "webhooks/providers/whatsapp", + "webhooks/providers/workos", + "webhooks/providers/zendesk", + "webhooks/providers/zoom" + ] + }, + "webhooks/custom-providers", "webhooks/deliveries", "webhooks/filters", "webhooks/waiters", @@ -181,7 +234,8 @@ "webhooks/channels", "webhooks/slack", "webhooks/linear", - "webhooks/human-in-the-loop" + "webhooks/human-in-the-loop", + "webhooks/own-handler" ] }, { @@ -542,6 +596,8 @@ "guides/frameworks/nextjs", "guides/frameworks/nodejs", "guides/frameworks/remix", + "guides/frameworks/nextjs-webhooks", + "guides/frameworks/remix-webhooks", "guides/community/sveltekit" ] }, @@ -581,20 +637,6 @@ "guides/frameworks/supabase-edge-functions-database-webhooks", "guides/frameworks/supabase-authentication" ] - }, - { - "group": "Webhooks", - "icon": { - "name": "webhook", - "style": "solid" - }, - "pages": [ - "guides/frameworks/webhooks-guides-overview", - "guides/frameworks/nextjs-webhooks", - "guides/frameworks/remix-webhooks", - "guides/examples/stripe-webhook", - "guides/examples/hookdeck-webhook" - ] } ] }, @@ -812,9 +854,25 @@ ] }, "redirects": [ + { + "source": "/webhooks/public-beta", + "destination": "/webhooks/overview" + }, + { + "source": "/guides/frameworks/webhooks-guides-overview", + "destination": "/webhooks/overview" + }, + { + "source": "/guides/examples/stripe-webhook", + "destination": "/webhooks/providers/stripe" + }, + { + "source": "/guides/examples/hookdeck-webhook", + "destination": "/webhooks/providers/hookdeck" + }, { "source": "/webhooks/private-beta", - "destination": "/webhooks/public-beta", + "destination": "/webhooks/overview", "permanent": true }, { diff --git a/docs/guides/examples/hookdeck-webhook.mdx b/docs/guides/examples/hookdeck-webhook.mdx deleted file mode 100644 index 8ef1778186a..00000000000 --- a/docs/guides/examples/hookdeck-webhook.mdx +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: "Trigger tasks from Hookdeck webhooks" -sidebarTitle: "Hookdeck webhooks" -description: "Forward webhooks from a Hookdeck connection to a hosted Trigger.dev endpoint, verified with the Hookdeck project's signing secret, and run a task for each event." ---- - -[Hookdeck](https://hookdeck.com) receives webhooks from external services, then queues, logs and forwards them to a destination. Point a Hookdeck connection at a hosted webhook endpoint and Trigger.dev verifies each forwarded request with the Hookdeck project's signing secret, deduplicates Hookdeck's retries, and runs your task with the original provider's payload. - -## Task code - -Declare the endpoint with `webhooks.hookdeck()` and subscribe a task to it. Hookdeck forwards the original provider's body unchanged, so pass that provider's event type. This example relays Stripe events: - -```ts /trigger/stripe-via-hookdeck.ts -import type Stripe from "stripe"; -import { webhook, webhooks } from "@trigger.dev/sdk"; - -export const stripeViaHookdeck = webhooks.endpoint.define({ - id: "stripe-via-hookdeck", - source: webhooks.hookdeck(), -}); - -export const paymentSucceeded = webhook({ - id: "payment-succeeded", - endpoint: stripeViaHookdeck, - filter: "event.type == 'payment_intent.succeeded'", - onEvent: async ({ event }) => { - console.log("Payment succeeded", event.id); - }, -}); -``` - -Run `trigger dev` or deploy, then copy the endpoint's URL from the Webhooks page in the dashboard. - -## Set up Hookdeck - - - - In the [Hookdeck dashboard](https://dashboard.hookdeck.com), create a [connection](https://hookdeck.com/docs/connections) from your source (for example a Stripe source) to an HTTP destination whose URL is the endpoint's URL. Keep the destination's authentication on **Hookdeck Signature**, the default for new destinations: Hookdeck only signs forwarded requests with it set. - - - Copy the signing secret from **Settings > Secrets** in Hookdeck and set it as the endpoint's signing secret in the Trigger.dev dashboard. It's one secret for the whole Hookdeck project. - - - -## Test it - -Send a webhook to your Hookdeck source URL, or trigger a real event in the upstream provider. In Hookdeck, the event shows a `200` response from the destination. In Trigger.dev, the endpoint shows a succeeded delivery and the `payment-succeeded` task has a completed run with the Stripe event as its payload. - -A request signed with a different secret gets a `400`, which Hookdeck reports as a failed attempt. - -## Rotate the signing secret - -Roll the signing secret under **Settings > Secrets** in Hookdeck with an expiry instead of expiring it immediately. Until the old secret expires, Hookdeck signs each request with both secrets, sending the previous secret's signature in `X-Hookdeck-Signature-2`. The endpoint accepts either, so deliveries keep verifying while you copy the new secret to Trigger.dev. Set a grace period when you store it to keep accepting the old secret for a while. - -## Deduplication - -Hookdeck retries and manual replays of the same event carry the same `X-Hookdeck-Eventid`, and the endpoint uses it as the [deduplication](/webhooks/deliveries#deduplication) key, so a retried event runs your task once. - -If you changed the header prefix in the Hookdeck project's settings, the event id arrives under the new prefix. Pass the prefix so deduplication keeps working: - -```ts /trigger/stripe-via-hookdeck.ts -import type Stripe from "stripe"; -import { webhooks } from "@trigger.dev/sdk"; - -export const stripeViaHookdeck = webhooks.endpoint.define({ - id: "stripe-via-hookdeck", - source: webhooks.hookdeck({ headerPrefix: "x-acme" }), -}); -``` - -The signature headers keep the `X-Hookdeck-` name whatever the prefix. - -## Trigger a task through the API instead - -You can also point a Hookdeck destination at the [trigger task API](/management/tasks/trigger) without a hosted endpoint. Hookdeck authenticates with your API key instead of a signature, and a transformation wraps the body in the `payload` field the API expects. - -1. Create a destination with the URL `https://api.trigger.dev/api/v1/tasks//trigger`, method `POST`, and **Bearer token** authentication using a **Trigger only** environment API key. -2. Add a [transformation](https://hookdeck.com/docs/transformations): - - ```javascript - addHandler("transform", (request, context) => { - request.body = { payload: { ...request.body } }; - return request; - }); - ``` - -3. Create a connection from your source to that destination and transformation. - -```ts /trigger/webhook-handler.ts -import { task } from "@trigger.dev/sdk"; - -export const webhookHandler = task({ - id: "webhook-handler", - run: async (payload: Record) => { - console.log("Received webhook:", payload); - }, -}); -``` - -This path has no deduplication of Hookdeck retries; each forwarded request triggers a run. - -For more on Hookdeck, see the [Hookdeck documentation](https://hookdeck.com/docs). diff --git a/docs/guides/examples/stripe-webhook.mdx b/docs/guides/examples/stripe-webhook.mdx deleted file mode 100644 index 588caf0bacb..00000000000 --- a/docs/guides/examples/stripe-webhook.mdx +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: "Trigger a task from Stripe webhook events" -sidebarTitle: "Stripe webhooks" -description: "This example demonstrates how to handle Stripe webhook events using Trigger.dev." ---- - -## Overview - -This example shows how to set up a webhook handler in your existing app for incoming Stripe events. The handler triggers a task when a `checkout.session.completed` event is received. This is easily customisable to handle other Stripe events. - -## Key features - -- Shows how to create a Stripe webhook handler in your app -- Triggers a task from your backend when a `checkout.session.completed` event is received - -## Environment variables - -You'll need to configure the following environment variables for this example to work: - -- `STRIPE_WEBHOOK_SECRET` The secret key used to verify the Stripe webhook signature. -- `TRIGGER_API_URL` Your Trigger.dev API url: `https://api.trigger.dev` -- `TRIGGER_SECRET_KEY` A named **Trigger only** API key from the Trigger.dev environment your app uses - -## Setting up the Stripe webhook handler - -First you'll need to create a [Stripe webhook](https://stripe.com/docs/webhooks) handler route that listens for POST requests and verifies the Stripe signature. - -Here are examples of how you can set up a handler using different frameworks: - - - -```ts Next.js -// app/api/stripe-webhook/route.ts -import { NextResponse } from "next/server"; -import { tasks } from "@trigger.dev/sdk"; -import Stripe from "stripe"; -import type { stripeCheckoutCompleted } from "@/trigger/stripe-checkout-completed"; -// 👆 **type-only** import - -export async function POST(request: Request) { - const signature = request.headers.get("stripe-signature"); - const payload = await request.text(); - - if (!signature || !payload) { - return NextResponse.json( - { error: "Invalid Stripe payload/signature" }, - { - status: 400, - } - ); - } - - const event = Stripe.webhooks.constructEvent( - payload, - signature, - process.env.STRIPE_WEBHOOK_SECRET as string - ); - - // Perform the check based on the event type - switch (event.type) { - case "checkout.session.completed": { - // Trigger the task only if the event type is "checkout.session.completed" - const { id } = await tasks.trigger( - "stripe-checkout-completed", - event.data.object - ); - return NextResponse.json({ runId: id }); - } - default: { - // Return a response indicating that the event is not handled - return NextResponse.json( - { message: "Event not handled" }, - { - status: 200, - } - ); - } - } -} -``` - -```ts Remix -// app/webhooks.stripe.ts -import { type ActionFunctionArgs, json } from "@remix-run/node"; -import type { stripeCheckoutCompleted } from "src/trigger/stripe-webhook"; -// 👆 **type-only** import -import { tasks } from "@trigger.dev/sdk"; -import Stripe from "stripe"; - -export async function action({ request }: ActionFunctionArgs) { - // Validate the Stripe webhook payload - const signature = request.headers.get("stripe-signature"); - const payload = await request.text(); - - if (!signature || !payload) { - return json({ error: "Invalid Stripe payload/signature" }, { status: 400 }); - } - - const event = Stripe.webhooks.constructEvent( - payload, - signature, - process.env.STRIPE_WEBHOOK_SECRET as string - ); - - // Perform the check based on the event type - switch (event.type) { - case "checkout.session.completed": { - // Trigger the task only if the event type is "checkout.session.completed" - const { id } = await tasks.trigger( - "stripe-checkout-completed", - event.data.object - ); - return json({ runId: id }); - } - default: { - // Return a response indicating that the event is not handled - return json({ message: "Event not handled" }, { status: 200 }); - } - } -} -``` - - - -## Task code - -This task is triggered when a `checkout.session.completed` event is received from Stripe. - -```ts trigger/stripe-checkout-completed.ts -import { task } from "@trigger.dev/sdk"; -import type stripe from "stripe"; - -export const stripeCheckoutCompleted = task({ - id: "stripe-checkout-completed", - run: async (payload: stripe.Checkout.Session) => { - // Add your custom logic for handling the checkout.session.completed event here - }, -}); -``` - -## Testing your task locally - -To test everything is working you can use the Stripe CLI to send test events to your endpoint: - -1. Install the [Stripe CLI](https://stripe.com/docs/stripe-cli#install), and login -2. Follow the instructions to [test your handler](https://docs.stripe.com/webhooks#test-webhook). This will include a temporary `STRIPE_WEBHOOK_SECRET` that you can use for testing. -3. When triggering the event, use the `checkout.session.completed` event type. With the Stripe CLI: `stripe trigger checkout.session.completed` -4. If your endpoint is set up correctly, you should see the Stripe events logged in your console with a status of `200`. -5. Then, check the [Trigger.dev](https://cloud.trigger.dev) dashboard and you should see the successful run of the `stripe-webhook` task. - -For more information on setting up and testing Stripe webhooks, refer to the [Stripe Webhook Documentation](https://stripe.com/docs/webhooks). diff --git a/docs/guides/frameworks/nextjs-webhooks.mdx b/docs/guides/frameworks/nextjs-webhooks.mdx index 25c91f07265..7bc19e0efab 100644 --- a/docs/guides/frameworks/nextjs-webhooks.mdx +++ b/docs/guides/frameworks/nextjs-webhooks.mdx @@ -1,11 +1,16 @@ --- -title: "Triggering tasks with webhooks in Next.js" -sidebarTitle: "Next.js webhooks" -description: "Learn how to trigger a task from a webhook in a Next.js app." +title: "Custom webhook handler with Next.js" +sidebarTitle: "Custom webhook handler with Next.js" +description: "Handle a webhook in your own Next.js API route and trigger a task from it." --- import VercelDocsCards from "/snippets/vercel-docs-cards.mdx"; + + Trigger.dev has built-in webhook endpoints that verify and route events for you. See + [Webhooks](/webhooks/overview). This guide is for when you want to handle webhooks in your own app and trigger tasks yourself. + + ## Prerequisites - [A Next.js project, set up with Trigger.dev](/guides/frameworks/nextjs) diff --git a/docs/guides/frameworks/remix-webhooks.mdx b/docs/guides/frameworks/remix-webhooks.mdx index a62d90cb9d0..2b2951b4f03 100644 --- a/docs/guides/frameworks/remix-webhooks.mdx +++ b/docs/guides/frameworks/remix-webhooks.mdx @@ -1,9 +1,14 @@ --- -title: "Triggering tasks with webhooks in Remix" -sidebarTitle: "Remix webhooks" -description: "Learn how to trigger a task from a webhook in a Remix app." +title: "Custom webhook handler with Remix" +sidebarTitle: "Custom webhook handler with Remix" +description: "Handle a webhook in your own Remix action and trigger a task from it." --- + + Trigger.dev has built-in webhook endpoints that verify and route events for you. See + [Webhooks](/webhooks/overview). This guide is for when you want to handle webhooks in your own app and trigger tasks yourself. + + ## Prerequisites - [A Remix project, set up with Trigger.dev](/guides/frameworks/remix) diff --git a/docs/guides/frameworks/supabase-edge-functions-database-webhooks.mdx b/docs/guides/frameworks/supabase-edge-functions-database-webhooks.mdx index f0fd2b5be80..0d957cc45b8 100644 --- a/docs/guides/frameworks/supabase-edge-functions-database-webhooks.mdx +++ b/docs/guides/frameworks/supabase-edge-functions-database-webhooks.mdx @@ -13,6 +13,11 @@ import NextjsTroubleshootingButtonSyntax from "/snippets/nextjs-button-syntax.md import SupabaseDocsCards from "/snippets/supabase-docs-cards.mdx"; import SupabaseAuthInfo from "/snippets/supabase-auth-info.mdx"; + + Trigger.dev has built-in webhook endpoints that verify and route events for you. See + [Webhooks](/webhooks/overview), including a [Supabase source](/webhooks/providers/supabase) for database webhooks. This guide is for when you want to handle webhooks in your own app and trigger tasks yourself. + + ## Overview Supabase and Trigger.dev can be used together to create powerful workflows triggered by real-time changes in your database tables: diff --git a/docs/guides/frameworks/webhooks-guides-overview.mdx b/docs/guides/frameworks/webhooks-guides-overview.mdx deleted file mode 100644 index 4c0a4404276..00000000000 --- a/docs/guides/frameworks/webhooks-guides-overview.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: "Using webhooks with Trigger.dev" -sidebarTitle: "Overview" -description: "Guides for using webhooks with Trigger.dev." ---- - -## Overview - -Webhooks are a way to send and receive events from external services. Triggering tasks using webhooks allow you to add real-time, event driven functionality to your app. - -A webhook handler is code that executes in response to an event. They can be endpoints in your framework's routing which can be triggered by an external service. - -## Webhook guides - - - - How to create a webhook handler in a Next.js app, and trigger a task from it. - - - How to create a webhook handler in a Remix app, and trigger a task from it. - - - How to create a Stripe webhook handler and trigger a task when a 'checkout session completed' - event is received. - - - Use Hookdeck to receive webhooks and forward them to Trigger.dev tasks with logging and replay - capabilities. - - - Learn how to trigger a task from a Supabase edge function when an event occurs in your database. - - diff --git a/docs/guides/introduction.mdx b/docs/guides/introduction.mdx index d354fea6ae3..d26cbcf88f1 100644 --- a/docs/guides/introduction.mdx +++ b/docs/guides/introduction.mdx @@ -37,12 +37,11 @@ Get set up fast using our detailed walk-through guides. | [Python PDF form extractor](/guides/python/python-pdf-form-extractor) | Use Python, PyMuPDF and Trigger.dev to extract data from a PDF form | | [Python web crawler](/guides/python/python-crawl4ai) | Use Python, Crawl4AI and Playwright to create a headless web crawler | | [Sequin database triggers](/guides/frameworks/sequin) | Trigger tasks from database changes using Sequin | -| [Stripe webhooks](/guides/examples/stripe-webhook) | Trigger tasks from incoming Stripe webhook events | -| [Hookdeck webhooks](/guides/examples/hookdeck-webhook) | Use Hookdeck to receive webhooks and forward them to Trigger.dev tasks | +| [Receiving webhooks](/webhooks/providers) | Receive webhooks from Stripe, GitHub, Firecrawl and 40+ other providers | | [Supabase database webhooks](/guides/frameworks/supabase-edge-functions-database-webhooks) | Trigger tasks using Supabase database webhooks | | [Supabase edge function hello world](/guides/frameworks/supabase-edge-functions-basic) | Trigger tasks from Supabase edge function | -| [Using webhooks in Next.js](/guides/frameworks/nextjs-webhooks) | Trigger tasks from a webhook in Next.js | -| [Using webhooks in Remix](/guides/frameworks/remix-webhooks) | Trigger tasks from a webhook in Remix | +| [Custom webhook handler with Next.js](/guides/frameworks/nextjs-webhooks) | Trigger tasks from a webhook in Next.js | +| [Custom webhook handler with Remix](/guides/frameworks/remix-webhooks) | Trigger tasks from a webhook in Remix | diff --git a/docs/snippets/examples-cards.mdx b/docs/snippets/examples-cards.mdx index 41333536e22..6345ec1684d 100644 --- a/docs/snippets/examples-cards.mdx +++ b/docs/snippets/examples-cards.mdx @@ -9,9 +9,9 @@ Task code you can copy and paste to use in your own projects, including OpenAI, Vercel AI SDK, Deepgram, FFmpeg, Puppeteer, Stripe, Supabase and more. - - Learn how to trigger tasks from webhooks, including Next.js, Remix, Supabase and Stripe and - more. + + Receive webhooks from Stripe, GitHub, Firecrawl, Supabase and 40+ other providers on hosted + endpoints. Full-stack projects demonstrating how to use Trigger.dev. Fork them in GitHub as a starting diff --git a/docs/webhooks/connect.mdx b/docs/webhooks/connect.mdx index 6b9ded15762..ad1b315e494 100644 --- a/docs/webhooks/connect.mdx +++ b/docs/webhooks/connect.mdx @@ -4,7 +4,7 @@ description: "Register an endpoint's URL and signing secret with the provider, b sidebarTitle: "Connect a provider" --- -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. +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 source](/webhooks/custom-providers) first. 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. diff --git a/docs/webhooks/custom-providers.mdx b/docs/webhooks/custom-providers.mdx new file mode 100644 index 00000000000..a5adb2e0ab3 --- /dev/null +++ b/docs/webhooks/custom-providers.mdx @@ -0,0 +1,85 @@ +--- +title: "Custom webhook providers" +sidebarTitle: "Custom providers" +description: "Verify webhooks from a provider that has no built-in source by passing your own HMAC, shared-secret, URL-secret or public-key configuration to webhooks.custom()." +--- + +**`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 source. + +## Define a custom source + +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: + +```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); + }, +}); +``` + + + +## Verification schemes + +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 (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. | + + + Query parameters can appear in access logs, proxies, and traces. Prefer a header-based scheme when + the provider supports one. + diff --git a/docs/webhooks/deliveries.mdx b/docs/webhooks/deliveries.mdx index 537d96c8745..9d57f50880b 100644 --- a/docs/webhooks/deliveries.mdx +++ b/docs/webhooks/deliveries.mdx @@ -94,7 +94,7 @@ When the source maps a provider event ID, that ID becomes the key, so the provid The other named sources (Zoom, Calendly, Sentry, DocuSign, ElevenLabs, Vapi, Retell, Tailscale, Infisical, PlanetScale, Supabase, Discord) use the fallback below. -If the source doesn't map an event ID, the key is derived from the raw body, timestamp, and signature. A retry with a different timestamp or signature can therefore produce a different key. For a [custom source](/webhooks/sources#custom-providers), set `idempotencyField` to a stable event identifier when the provider supplies one. +If the source doesn't map an event ID, the key is derived from the raw body, timestamp, and signature. A retry with a different timestamp or signature can therefore produce a different key. For a [custom source](/webhooks/custom-providers), set `idempotencyField` to a stable event identifier when the provider supplies one. ## Verification and recording diff --git a/docs/webhooks/overview.mdx b/docs/webhooks/overview.mdx index 264e4f18ec4..f4aeaae105c 100644 --- a/docs/webhooks/overview.mdx +++ b/docs/webhooks/overview.mdx @@ -6,6 +6,15 @@ sidebarTitle: "Overview" **A webhook endpoint is one hosted URL that you register with a provider.** Trigger.dev verifies every request against the endpoint's [source](/webhooks/sources), records it as a [delivery](/webhooks/deliveries), and hands the event to everything subscribed to the endpoint. + + Webhooks are in public beta for every organization, in `@trigger.dev/sdk` 4.8.1 and later. The API + may change before general availability; we announce changes in the + [changelog](https://trigger.dev/changelog). Send bugs and feedback to + [eric@trigger.dev](mailto:eric@trigger.dev) with the delivery id (`whd_...`) or run id. + + +[Built-in sources](/webhooks/providers) cover Stripe, GitHub, Firecrawl, Linear and more than 40 other providers. To set one up from scratch, follow the [quick start](/webhooks/quick-start). + Declare the endpoint once, then subscribe to it: ```ts /trigger/stripe.ts @@ -91,16 +100,27 @@ A delivery that no subscriber's filter matches starts no run for any subscriber, Each plan sets limits on the ingest rate, waiting runs, processing concurrency and how long deliveries are kept. See [Limits](/limits#webhook-ingest-rate-limits). +Webhooks are open source, so they also work self-hosted. See [Self-hosting webhooks](/self-hosting/env/webapp#webhooks) to turn them on. + ## Connect it Every endpoint can produce a setup prompt for an AI coding agent. It holds the URL, the events your subscribers filter on, and the steps for registering the endpoint and its signing secret with the provider. Copy it from the endpoints list or the endpoint's page, or read it with the MCP server's `get_webhook_endpoint_details` tool. See [Connect a provider](/webhooks/connect). + + Install the SDK, declare an endpoint, and receive your first event. + Register the URL and signing secret, then send a test event. + + Set up each built-in provider source. + + + Verify a provider that has no built-in source. + - Choose a provider source or define a custom verification scheme. + How sources verify requests and type the event. Choose which events reach each subscriber. diff --git a/docs/webhooks/own-handler.mdx b/docs/webhooks/own-handler.mdx new file mode 100644 index 00000000000..9842c54a9bb --- /dev/null +++ b/docs/webhooks/own-handler.mdx @@ -0,0 +1,58 @@ +--- +title: "Use your own webhook handler" +sidebarTitle: "Using your own handler" +description: "Receive a webhook in a route in your own app, verify it yourself, and trigger a task from it instead of using a hosted endpoint." +--- + +**A webhook handler in your own app can trigger a task with `tasks.trigger()`, the same way any backend code does.** Use it when you need to handle the request yourself. For most providers, a hosted [webhook endpoint](/webhooks/overview) does the same job with less code. + +## When to use your own handler + +| Use a hosted endpoint | Use your own handler | +| --- | --- | +| You want Trigger.dev to verify signatures, deduplicate retries and record deliveries. | You already have a handler in production and only want to move the work into a task. | +| One event should reach several tasks, agents or waiting runs. | The provider needs a response body that your code computes from the request. | +| You want to replay deliveries and see which runs each one started. | The request must pass through your app first, for example to look up a tenant before triggering. | + +## Trigger a task from your route + +Verify the request with the provider's SDK, then trigger the task. This Next.js route uses Stripe's SDK; import the task as a type so the route doesn't bundle the task code. + +```ts app/api/webhooks/stripe/route.ts +import Stripe from "stripe"; +import { tasks } from "@trigger.dev/sdk"; +import type { handleStripeEvent } from "@/trigger/handle-stripe-event"; + +const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!); + +export async function POST(request: Request) { + const body = await request.text(); + + // Verify the signature before trusting the body + const event = stripe.webhooks.constructEvent( + body, + request.headers.get("stripe-signature")!, + process.env.STRIPE_WEBHOOK_SECRET! + ); + + await tasks.trigger("handle-stripe-event", event, { + // Retries of the same event start one run + idempotencyKey: event.id, + }); + + return Response.json({ received: true }); +} +``` + +Return quickly: the task runs in the background, so the provider gets its response before the work starts. + +## Framework guides + + + + Handle a webhook in a Next.js API route and trigger a task. + + + Handle a webhook in a Remix action and trigger a task. + + diff --git a/docs/webhooks/providers.mdx b/docs/webhooks/providers.mdx new file mode 100644 index 00000000000..b6a1a8cd622 --- /dev/null +++ b/docs/webhooks/providers.mdx @@ -0,0 +1,58 @@ +--- +title: "Webhook providers" +sidebarTitle: "All providers" +description: "Every built-in webhook source, with its SDK function, the credential it verifies with, and a setup page for each provider." +--- + +**Each built-in source verifies one provider's signature scheme, so you declare the endpoint with one function call and set one credential.** Every provider below has a page with the source, where to register the URL, and how to set the credential. + +| Provider | Source | Credential | +| --- | --- | --- | +| [Attio](/webhooks/providers/attio) | `webhooks.attio()` | You generate it, or the provider issues it | +| [Autumn](/webhooks/providers/autumn) | `webhooks.autumn()` | Issued by the provider | +| [Brex](/webhooks/providers/brex) | `webhooks.brex()` | Issued by the provider | +| [Cal.com](/webhooks/providers/cal-com) | `webhooks.calCom()` | You generate it, or the provider issues it | +| [Calendly](/webhooks/providers/calendly) | `webhooks.calendly()` | Issued by the provider | +| [Clerk](/webhooks/providers/clerk) | `webhooks.clerk()` | Issued by the provider | +| [Composio](/webhooks/providers/composio) | `webhooks.composio()` | Issued by the provider | +| [Discord](/webhooks/providers/discord) | `webhooks.discord()` | Provider's public key | +| [DocuSign](/webhooks/providers/docusign) | `webhooks.docusign()` | You generate it, or the provider issues it | +| [ElevenLabs](/webhooks/providers/elevenlabs) | `webhooks.elevenlabs()` | Issued by the provider | +| [Firecrawl](/webhooks/providers/firecrawl) | `webhooks.firecrawl()` | Issued by the provider | +| [GitHub](/webhooks/providers/github) | `webhooks.github()` | You generate it | +| [GitLab](/webhooks/providers/gitlab) | `webhooks.gitlab()` | You generate it | +| [Granola](/webhooks/providers/granola) | `webhooks.granola()` | Issued by the provider | +| [Hookdeck](/webhooks/providers/hookdeck) | `webhooks.hookdeck()` | Issued by the provider | +| [Infisical](/webhooks/providers/infisical) | `webhooks.infisical()` | You generate it | +| [Intercom](/webhooks/providers/intercom) | `webhooks.intercom()` | You generate it, or the provider issues it | +| [Jira](/webhooks/providers/jira) | `webhooks.jira()` | You generate it, or the provider issues it | +| [Langfuse](/webhooks/providers/langfuse) | `webhooks.langfuse()` | Issued by the provider | +| [Linear](/webhooks/providers/linear) | `webhooks.linear()` | You generate it, or the provider issues it | +| [Loops](/webhooks/providers/loops) | `webhooks.loops()` | Issued by the provider | +| [Metronome](/webhooks/providers/metronome) | `webhooks.metronome()` | Issued by the provider | +| [Mux](/webhooks/providers/mux) | `webhooks.mux()` | Issued by the provider | +| [Notion](/webhooks/providers/notion) | `webhooks.notion()` | Issued by the provider | +| [OpenAI](/webhooks/providers/openai) | `webhooks.openai()` | Issued by the provider | +| [PagerDuty](/webhooks/providers/pagerduty) | `webhooks.pagerduty()` | You generate it, or the provider issues it | +| [Plain](/webhooks/providers/plain) | `webhooks.plain()` | Issued by the provider | +| [PlanetScale](/webhooks/providers/planetscale) | `webhooks.planetscale()` | Issued by the provider | +| [Recall.ai](/webhooks/providers/recall-ai) | `webhooks.recallai()` | Issued by the provider | +| [Replicate](/webhooks/providers/replicate) | `webhooks.replicate()` | Issued by the provider | +| [Resend](/webhooks/providers/resend) | `webhooks.resend()` | Issued by the provider | +| [Retell AI](/webhooks/providers/retell) | `webhooks.retell()` | Issued by the provider | +| [Sentry](/webhooks/providers/sentry) | `webhooks.sentry()` | You generate it, or the provider issues it | +| [Shopify](/webhooks/providers/shopify) | `webhooks.shopify()` | Issued by the provider | +| [Slack](/webhooks/providers/slack) | `webhookSource()` (`@trigger.dev/slack`) | Issued by the provider | +| [Square](/webhooks/providers/square) | `webhooks.square()` | Issued by the provider | +| [Stripe](/webhooks/providers/stripe) | `webhooks.stripe()` | Issued by the provider | +| [Supabase](/webhooks/providers/supabase) | `webhooks.supabase()` | You generate it | +| [Tailscale](/webhooks/providers/tailscale) | `webhooks.tailscale()` | Issued by the provider | +| [Typeform](/webhooks/providers/typeform) | `webhooks.typeform()` | You generate it, or the provider issues it | +| [Vapi](/webhooks/providers/vapi) | `webhooks.vapi()` | You generate it, or the provider issues it | +| [Vercel](/webhooks/providers/vercel) | `webhooks.vercel()` | You generate it, or the provider issues it | +| [WhatsApp](/webhooks/providers/whatsapp) | `webhooks.whatsapp()` | Issued by the provider | +| [WorkOS](/webhooks/providers/workos) | `webhooks.workos()` | Issued by the provider | +| [Zendesk](/webhooks/providers/zendesk) | `webhooks.zendesk()` | You generate it, or the provider issues it | +| [Zoom](/webhooks/providers/zoom) | `webhooks.zoom()` | Issued by the provider | + +For a provider that isn't listed, define a [custom source](/webhooks/custom-providers). For providers that sign with Svix or Standard Webhooks, `webhooks.svix()` and `webhooks.standardWebhooks()` also work; see [Sources and verification](/webhooks/sources#svix-and-standard-webhooks). diff --git a/docs/webhooks/providers/attio.mdx b/docs/webhooks/providers/attio.mdx new file mode 100644 index 00000000000..e60bea6e84d --- /dev/null +++ b/docs/webhooks/providers/attio.mdx @@ -0,0 +1,38 @@ +--- +title: "Attio webhooks" +sidebarTitle: "Attio" +description: "Receive Attio webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Attio, and how to set the signing credential." +--- + +**`webhooks.attio()` verifies Attio's signature on every request, so subscribers only receive genuine Attio events.** + +```ts /trigger/attio.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const attio = webhooks.endpoint.define({ + id: "attio", + source: webhooks.attio(), +}); + +export const attioEvents = webhook({ + id: "attio-events", + endpoint: attio, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.attio()` | +| Verification | HMAC-SHA256 in `attio-signature` | +| Credential | Signing secret you generate on Trigger.dev, or one issued by Attio | +| Attio docs | [Attio webhook docs](https://docs.attio.com/rest-api/guides/webhooks) | + +## Set up Attio + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as a webhook in Attio and select the events your subscribers need. See Attio's [webhook docs](https://docs.attio.com/rest-api/guides/webhooks) for where its webhook settings are. +3. If Attio shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Attio asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Attio. +4. Send a test event from Attio, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/autumn.mdx b/docs/webhooks/providers/autumn.mdx new file mode 100644 index 00000000000..04d111794f8 --- /dev/null +++ b/docs/webhooks/providers/autumn.mdx @@ -0,0 +1,41 @@ +--- +title: "Autumn webhooks" +sidebarTitle: "Autumn" +description: "Receive Autumn webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Autumn, and how to set the signing credential." +--- + +**`webhooks.autumn()` verifies Autumn's signature on every request, so subscribers only receive genuine Autumn events.** + +```ts /trigger/autumn.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const autumn = webhooks.endpoint.define({ + id: "autumn", + source: webhooks.autumn(), +}); + +export const autumnEvents = webhook({ + id: "autumn-events", + endpoint: autumn, + filter: "event.type == 'billing.updated'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.autumn()` | +| Verification | Svix (`svix-id`, `svix-timestamp`, `svix-signature`) | +| Credential | Signing secret issued by Autumn | +| Event type | `event.type` | +| Autumn docs | [Autumn webhook docs](https://docs.useautumn.com/documentation/webhooks) | + +## Set up Autumn + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Ask Autumn support to turn on webhooks for your account; they are in beta. +3. In the Autumn dashboard's webhook settings, add the webhook URL as an endpoint and select the event types your subscribers need. +4. Copy the endpoint's signing secret (it starts with `whsec_`), then choose **Set signing secret** on the Trigger.dev endpoint. +5. Send a test event from Autumn, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/brex.mdx b/docs/webhooks/providers/brex.mdx new file mode 100644 index 00000000000..390fa5688f8 --- /dev/null +++ b/docs/webhooks/providers/brex.mdx @@ -0,0 +1,41 @@ +--- +title: "Brex webhooks" +sidebarTitle: "Brex" +description: "Receive Brex webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Brex, and how to set the signing credential." +--- + +**`webhooks.brex()` verifies Brex's signature on every request, so subscribers only receive genuine Brex events.** + +```ts /trigger/brex.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const brex = webhooks.endpoint.define({ + id: "brex", + source: webhooks.brex(), +}); + +export const brexEvents = webhook({ + id: "brex-events", + endpoint: brex, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event_type`. + +| | | +| --- | --- | +| Source | `webhooks.brex()` | +| Verification | Svix (`svix-id`, `svix-timestamp`, `svix-signature`) | +| Credential | Signing secret issued by Brex | +| Event type | `event.event_type` | +| Brex docs | [Brex webhook docs](https://developer.brex.com/docs/webhooks/) | + +## Set up Brex + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as an endpoint in Brex's webhook settings and subscribe it to the event types your subscribers need. +3. Copy the endpoint's signing secret (it starts with `whsec_`), then choose **Set signing secret** on the Trigger.dev endpoint. +4. Send a test event from Brex, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/cal-com.mdx b/docs/webhooks/providers/cal-com.mdx new file mode 100644 index 00000000000..9327dba4660 --- /dev/null +++ b/docs/webhooks/providers/cal-com.mdx @@ -0,0 +1,41 @@ +--- +title: "Cal.com webhooks" +sidebarTitle: "Cal.com" +description: "Receive Cal.com webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Cal.com, and how to set the signing credential." +--- + +**`webhooks.calCom()` verifies Cal.com's signature on every request, so subscribers only receive genuine Cal.com events.** + +```ts /trigger/cal-com.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const calCom = webhooks.endpoint.define({ + id: "cal-com", + source: webhooks.calCom(), +}); + +export const calComEvents = webhook({ + id: "cal-com-events", + endpoint: calCom, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.triggerEvent`. + +| | | +| --- | --- | +| Source | `webhooks.calCom()` | +| Verification | HMAC-SHA256 in `x-cal-signature-256` | +| Credential | Signing secret you generate on Trigger.dev, or one issued by Cal.com | +| Event type | `event.triggerEvent` | +| Cal.com docs | [Cal.com webhook docs](https://cal.com/docs/developing/guides/automation/webhooks) | + +## Set up Cal.com + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as a webhook in Cal.com and select the events your subscribers need. See Cal.com's [webhook docs](https://cal.com/docs/developing/guides/automation/webhooks) for where its webhook settings are. +3. If Cal.com shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Cal.com asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Cal.com. +4. Send a test event from Cal.com, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/calendly.mdx b/docs/webhooks/providers/calendly.mdx new file mode 100644 index 00000000000..9306074a957 --- /dev/null +++ b/docs/webhooks/providers/calendly.mdx @@ -0,0 +1,41 @@ +--- +title: "Calendly webhooks" +sidebarTitle: "Calendly" +description: "Receive Calendly webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Calendly, and how to set the signing credential." +--- + +**`webhooks.calendly()` verifies Calendly's signature on every request, so subscribers only receive genuine Calendly events.** + +```ts /trigger/calendly.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const calendly = webhooks.endpoint.define({ + id: "calendly", + source: webhooks.calendly(), +}); + +export const calendlyEvents = webhook({ + id: "calendly-events", + endpoint: calendly, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event`. + +| | | +| --- | --- | +| Source | `webhooks.calendly()` | +| Verification | HMAC-SHA256 in `calendly-webhook-signature` | +| Credential | Signing secret issued by Calendly | +| Event type | `event.event` | +| Calendly docs | [Calendly webhook docs](https://developer.calendly.com/api-docs/4c305798a61d3-webhook-signatures) | + +## Set up Calendly + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as a webhook in Calendly and select the events your subscribers need. See Calendly's [webhook docs](https://developer.calendly.com/api-docs/4c305798a61d3-webhook-signatures) for where its webhook settings are. +3. Copy the signing secret Calendly shows for the webhook, then choose **Set signing secret** on the Trigger.dev endpoint. +4. Send a test event from Calendly, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/clerk.mdx b/docs/webhooks/providers/clerk.mdx new file mode 100644 index 00000000000..27344e4421e --- /dev/null +++ b/docs/webhooks/providers/clerk.mdx @@ -0,0 +1,40 @@ +--- +title: "Clerk webhooks" +sidebarTitle: "Clerk" +description: "Receive Clerk webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Clerk, and how to set the signing credential." +--- + +**`webhooks.clerk()` verifies Clerk's signature on every request, so subscribers only receive genuine Clerk events.** + +```ts /trigger/clerk.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const clerk = webhooks.endpoint.define({ + id: "clerk", + source: webhooks.clerk(), +}); + +export const clerkEvents = webhook({ + id: "clerk-events", + endpoint: clerk, + filter: "event.type == 'user.created'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.clerk()` | +| Verification | Svix (`svix-id`, `svix-timestamp`, `svix-signature`) | +| Credential | Signing secret issued by Clerk | +| Event type | `event.type` | +| Clerk docs | [Clerk webhook docs](https://clerk.com/docs/integrations/webhooks/overview) | + +## Set up Clerk + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as an endpoint in Clerk's webhook settings and subscribe it to the event types your subscribers need. +3. Copy the endpoint's signing secret (it starts with `whsec_`), then choose **Set signing secret** on the Trigger.dev endpoint. +4. Send a test event from Clerk, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/composio.mdx b/docs/webhooks/providers/composio.mdx new file mode 100644 index 00000000000..fcb17ff36dd --- /dev/null +++ b/docs/webhooks/providers/composio.mdx @@ -0,0 +1,40 @@ +--- +title: "Composio webhooks" +sidebarTitle: "Composio" +description: "Receive Composio webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Composio, and how to set the signing credential." +--- + +**`webhooks.composio()` verifies Composio's signature on every request, so subscribers only receive genuine Composio events.** + +```ts /trigger/composio.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const composio = webhooks.endpoint.define({ + id: "composio", + source: webhooks.composio(), +}); + +export const composioEvents = webhook({ + id: "composio-events", + endpoint: composio, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.type`. + +| | | +| --- | --- | +| Source | `webhooks.composio()` | +| Verification | Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`) | +| Credential | Signing secret issued by Composio | +| Event type | `event.type` | + +## Set up Composio + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as an endpoint in Composio's webhook settings and subscribe it to the event types your subscribers need. +3. Copy the endpoint's signing secret (it starts with `whsec_`), then choose **Set signing secret** on the Trigger.dev endpoint. +4. Send a test event from Composio, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/discord.mdx b/docs/webhooks/providers/discord.mdx new file mode 100644 index 00000000000..74fc8e762c0 --- /dev/null +++ b/docs/webhooks/providers/discord.mdx @@ -0,0 +1,45 @@ +--- +title: "Discord webhooks" +sidebarTitle: "Discord" +description: "Receive Discord webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Discord, and how to set the signing credential." +--- + +**`webhooks.discord()` verifies Discord's signature on every request, so subscribers only receive genuine Discord events.** + +```ts /trigger/discord.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const discord = webhooks.endpoint.define({ + id: "discord", + source: webhooks.discord(), +}); + +export const discordEvents = webhook({ + id: "discord-events", + endpoint: discord, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event.type`. + +| | | +| --- | --- | +| Source | `webhooks.discord()` | +| Verification | Ed25519 signature in `x-signature-ed25519` | +| Credential | Discord's public key | +| Event type | `event.event.type` | +| Discord docs | [Discord webhook docs](https://docs.discord.com/developers/events/webhook-events) | + +## Set up Discord + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. In the [Discord Developer Portal](https://discord.com/developers/applications), open the application, then its **Webhooks** page. Set the **Endpoint URL** to the webhook URL, turn **Events** on, and select the event types your subscribers need. +3. Copy the **Public Key** from the application's **General Information** page, then choose **Set public key** on the Trigger.dev endpoint. Discord sends a PING that the endpoint answers once the key is set. +4. Send a test event from Discord, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. + +## Endpoint validation + +The endpoint answers Discord's verified PING with an empty `204`, so the PING creates no delivery or run. diff --git a/docs/webhooks/providers/docusign.mdx b/docs/webhooks/providers/docusign.mdx new file mode 100644 index 00000000000..83dffa3cbdf --- /dev/null +++ b/docs/webhooks/providers/docusign.mdx @@ -0,0 +1,41 @@ +--- +title: "DocuSign webhooks" +sidebarTitle: "DocuSign" +description: "Receive DocuSign webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in DocuSign, and how to set the signing credential." +--- + +**`webhooks.docusign()` verifies DocuSign's signature on every request, so subscribers only receive genuine DocuSign events.** + +```ts /trigger/docusign.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const docusign = webhooks.endpoint.define({ + id: "docusign", + source: webhooks.docusign(), +}); + +export const docusignEvents = webhook({ + id: "docusign-events", + endpoint: docusign, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event`. + +| | | +| --- | --- | +| Source | `webhooks.docusign()` | +| Verification | HMAC-SHA256 in `x-docusign-signature-1` | +| Credential | Signing secret you generate on Trigger.dev, or one issued by DocuSign | +| Event type | `event.event` | +| DocuSign docs | [DocuSign webhook docs](https://developers.docusign.com/platform/webhooks/connect/) | + +## Set up DocuSign + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as a webhook in DocuSign and select the events your subscribers need. See DocuSign's [webhook docs](https://developers.docusign.com/platform/webhooks/connect/) for where its webhook settings are. +3. If DocuSign shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If DocuSign asks you for a secret, choose **Generate secret** on the endpoint and paste the value into DocuSign. +4. Send a test event from DocuSign, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/elevenlabs.mdx b/docs/webhooks/providers/elevenlabs.mdx new file mode 100644 index 00000000000..842fca4b24f --- /dev/null +++ b/docs/webhooks/providers/elevenlabs.mdx @@ -0,0 +1,41 @@ +--- +title: "ElevenLabs webhooks" +sidebarTitle: "ElevenLabs" +description: "Receive ElevenLabs webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in ElevenLabs, and how to set the signing credential." +--- + +**`webhooks.elevenlabs()` verifies ElevenLabs's signature on every request, so subscribers only receive genuine ElevenLabs events.** + +```ts /trigger/elevenlabs.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const elevenlabs = webhooks.endpoint.define({ + id: "elevenlabs", + source: webhooks.elevenlabs(), +}); + +export const elevenlabsEvents = webhook({ + id: "elevenlabs-events", + endpoint: elevenlabs, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.type`. + +| | | +| --- | --- | +| Source | `webhooks.elevenlabs()` | +| Verification | HMAC-SHA256 in `elevenlabs-signature` | +| Credential | Signing secret issued by ElevenLabs | +| Event type | `event.type` | +| ElevenLabs docs | [ElevenLabs webhook docs](https://elevenlabs.io/docs/eleven-agents/workflows/post-call-webhooks) | + +## Set up ElevenLabs + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as a webhook in ElevenLabs and select the events your subscribers need. See ElevenLabs's [webhook docs](https://elevenlabs.io/docs/eleven-agents/workflows/post-call-webhooks) for where its webhook settings are. +3. Copy the signing secret ElevenLabs shows for the webhook, then choose **Set signing secret** on the Trigger.dev endpoint. +4. Send a test event from ElevenLabs, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/firecrawl.mdx b/docs/webhooks/providers/firecrawl.mdx new file mode 100644 index 00000000000..53be82383c7 --- /dev/null +++ b/docs/webhooks/providers/firecrawl.mdx @@ -0,0 +1,54 @@ +--- +title: "Firecrawl webhooks" +sidebarTitle: "Firecrawl" +description: "Receive Firecrawl webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Firecrawl, and how to set the signing credential." +--- + +**`webhooks.firecrawl()` verifies Firecrawl's signature on every request, so subscribers only receive genuine Firecrawl events.** + +```ts /trigger/firecrawl.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const firecrawl = webhooks.endpoint.define({ + id: "firecrawl", + source: webhooks.firecrawl(), +}); + +export const firecrawlEvents = webhook({ + id: "firecrawl-events", + endpoint: firecrawl, + filter: "event.type == 'crawl.completed'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.firecrawl()` | +| Verification | HMAC-SHA256 in `x-firecrawl-signature` | +| Credential | Signing secret issued by Firecrawl | +| Event type | `event.type` | +| Firecrawl docs | [Firecrawl webhook docs](https://docs.firecrawl.dev/webhooks/overview) | + +## Set up Firecrawl + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Copy the webhook secret from the **Advanced** tab of your Firecrawl account settings. It is one secret for the whole account. +3. Choose **Set signing secret** on the Trigger.dev endpoint and paste it. +4. Firecrawl has no webhook settings page. Pass a `webhook` object with the URL and events on each crawl, batch scrape, extract or agent request instead: + + ```ts Your crawl code + await firecrawl.crawl("https://example.com", { + webhook: { + url: "", + events: ["started", "page", "completed"], + }, + }); + ``` +5. Start a crawl with the `webhook` object, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. + +## Example task + +The [Firecrawl URL crawl example](/guides/examples/firecrawl-url-crawl) crawls a site from a task. Add the `webhook` object above to receive each page as a delivery. diff --git a/docs/webhooks/providers/github.mdx b/docs/webhooks/providers/github.mdx new file mode 100644 index 00000000000..0a4c5edccfe --- /dev/null +++ b/docs/webhooks/providers/github.mdx @@ -0,0 +1,46 @@ +--- +title: "GitHub webhooks" +sidebarTitle: "GitHub" +description: "Receive GitHub webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in GitHub, and how to set the signing credential." +--- + +**`webhooks.github()` verifies GitHub's signature on every request, so subscribers only receive genuine GitHub events.** + +```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, + filter: "header.x-github-event == 'issues'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.github()` | +| Verification | HMAC-SHA256 in `x-hub-signature-256` | +| Credential | Secret you generate on Trigger.dev | +| Event type | `header.x-github-event` | +| GitHub docs | [GitHub webhook docs](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries) | + +## Set up GitHub + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Choose **Generate secret** on the Trigger.dev endpoint and copy the value. GitHub accepts a secret you choose. +3. Create the webhook. For a repository webhook with the `gh` CLI: + + ```bash + gh api repos/OWNER/REPO/hooks -f name=web -f "config[url]=" -f "config[content_type]=json" -f "config[secret]=" -f "events[]=issues" -F active=true + ``` + + Use `orgs/ORG/hooks` for an organization webhook. For a GitHub App, set the webhook URL and secret in the app's settings. Set the content type to `json`. +4. Trigger an event in the repository, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/gitlab.mdx b/docs/webhooks/providers/gitlab.mdx new file mode 100644 index 00000000000..919b53e0700 --- /dev/null +++ b/docs/webhooks/providers/gitlab.mdx @@ -0,0 +1,41 @@ +--- +title: "GitLab webhooks" +sidebarTitle: "GitLab" +description: "Receive GitLab webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in GitLab, and how to set the signing credential." +--- + +**`webhooks.gitlab()` checks the secret token GitLab sends with every request, so subscribers only receive genuine GitLab events.** + +```ts /trigger/gitlab.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const gitlab = webhooks.endpoint.define({ + id: "gitlab", + source: webhooks.gitlab(), +}); + +export const gitlabEvents = webhook({ + id: "gitlab-events", + endpoint: gitlab, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `header.x-gitlab-event`. + +| | | +| --- | --- | +| Source | `webhooks.gitlab()` | +| Verification | Shared secret in `x-gitlab-token` | +| Credential | Secret you generate on Trigger.dev | +| Event type | `header.x-gitlab-event` | +| GitLab docs | [GitLab webhook docs](https://docs.gitlab.com/user/project/integrations/webhooks/) | + +## Set up GitLab + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Choose **Generate secret** on the Trigger.dev endpoint and copy the value. +3. In the GitLab project or group, go to **Settings > Webhooks** and add a webhook with the webhook URL. Paste the secret into **Secret token** and select the triggers your subscribers need. GitLab sends the event name in the `x-gitlab-event` header. +4. Send a test event from GitLab, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/granola.mdx b/docs/webhooks/providers/granola.mdx new file mode 100644 index 00000000000..972acf0d150 --- /dev/null +++ b/docs/webhooks/providers/granola.mdx @@ -0,0 +1,44 @@ +--- +title: "Granola webhooks" +sidebarTitle: "Granola" +description: "Receive Granola webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Granola, and how to set the signing credential." +--- + +**`webhooks.granola()` verifies Granola's signature on every request, so subscribers only receive genuine Granola events.** + +```ts /trigger/granola.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const granola = webhooks.endpoint.define({ + id: "granola", + source: webhooks.granola(), +}); + +export const granolaEvents = webhook({ + id: "granola-events", + endpoint: granola, + filter: "event.event_type == 'note.generated'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.granola()` | +| Verification | Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`) | +| Credential | Signing secret issued by Granola | +| Event type | `event.event_type` | +| Granola docs | [Granola webhook docs](https://docs.granola.ai/webhooks) | + +## Set up Granola + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Create the endpoint in Granola under **Settings > Connectors > Webhooks**, or under a folder's **Integrations > Webhooks** to limit it to that folder. Granola webhooks need a Business or Enterprise plan. +3. Granola shows the signing secret (it starts with `whsec_`) once, when the endpoint is created. Choose **Set signing secret** on the Trigger.dev endpoint and paste it. +4. Send a test event from Granola, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. + +## Fetching the note + +Deliveries carry the note id but not its content. Fetch the note with Granola's API inside `onEvent`. diff --git a/docs/webhooks/providers/hookdeck.mdx b/docs/webhooks/providers/hookdeck.mdx new file mode 100644 index 00000000000..99226a95420 --- /dev/null +++ b/docs/webhooks/providers/hookdeck.mdx @@ -0,0 +1,69 @@ +--- +title: "Hookdeck webhooks" +sidebarTitle: "Hookdeck" +description: "Receive Hookdeck webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Hookdeck, and how to set the signing credential." +--- + +**`webhooks.hookdeck()` verifies requests that a Hookdeck connection forwards, so you can put Hookdeck in front of any provider.** + +```ts /trigger/hookdeck.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const hookdeck = webhooks.endpoint.define({ + id: "hookdeck", + source: webhooks.hookdeck(), +}); + +export const hookdeckEvents = webhook({ + id: "hookdeck-events", + endpoint: hookdeck, + filter: "event.type == 'payment_intent.succeeded'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.hookdeck()` | +| Verification | HMAC-SHA256 in `x-hookdeck-signature` | +| Credential | Signing secret issued by Hookdeck | +| Event type | `event.type` | +| Hookdeck docs | [Hookdeck webhook docs](https://hookdeck.com/docs/authentication) | + +## Set up Hookdeck + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. In Hookdeck, create a connection whose destination is an HTTP destination with the webhook URL. Keep the destination's authentication on **Hookdeck Signature** (the default); Hookdeck only signs requests with it set. +3. Copy the project's signing secret from [**Settings > Secrets**](https://dashboard.hookdeck.com/settings/project/secrets), then choose **Set signing secret** on the Trigger.dev endpoint. It is one secret for the whole project. +4. Send a test event from Hookdeck, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. + +## Typing the event + +Hookdeck forwards the original provider's body unchanged, so pass that provider's event type: + +```ts /trigger/stripe-via-hookdeck.ts +import type Stripe from "stripe"; +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const stripeViaHookdeck = webhooks.endpoint.define({ + id: "stripe-via-hookdeck", + source: webhooks.hookdeck(), +}); + +export const paymentSucceeded = webhook({ + id: "payment-succeeded", + endpoint: stripeViaHookdeck, + filter: "event.type == 'payment_intent.succeeded'", + onEvent: async ({ event }) => { + console.log(event.id); + }, +}); +``` + +## Rotation, deduplication and header prefix + +- **Secret rotation:** when you roll the signing secret in Hookdeck with an expiry, Hookdeck also signs each request with the previous secret in `X-Hookdeck-Signature-2`, so deliveries keep verifying until you store the new secret. +- **Deduplication:** retries dedupe on `X-Hookdeck-Eventid`, which is the same on every attempt of a Hookdeck event. +- **Custom header prefix:** if you changed the header prefix in the Hookdeck project's settings, pass it with `webhooks.hookdeck({ headerPrefix: "x-acme" })`. The prefix renames the event id header; the signature headers keep the `X-Hookdeck-` name. diff --git a/docs/webhooks/providers/infisical.mdx b/docs/webhooks/providers/infisical.mdx new file mode 100644 index 00000000000..dc67082238a --- /dev/null +++ b/docs/webhooks/providers/infisical.mdx @@ -0,0 +1,41 @@ +--- +title: "Infisical webhooks" +sidebarTitle: "Infisical" +description: "Receive Infisical webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Infisical, and how to set the signing credential." +--- + +**`webhooks.infisical()` verifies Infisical's signature on every request, so subscribers only receive genuine Infisical events.** + +```ts /trigger/infisical.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const infisical = webhooks.endpoint.define({ + id: "infisical", + source: webhooks.infisical(), +}); + +export const infisicalEvents = webhook({ + id: "infisical-events", + endpoint: infisical, + filter: "event.event == 'secrets.modified'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.infisical()` | +| Verification | HMAC-SHA256 in `x-infisical-signature` | +| Credential | Secret you generate on Trigger.dev | +| Event type | `event.event` | +| Infisical docs | [Infisical webhook docs](https://infisical.com/docs/documentation/platform/webhooks) | + +## Set up Infisical + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Choose **Generate secret** on the Trigger.dev endpoint and copy the value. +3. In Infisical, go to **Project Settings > Webhooks** and create a **General** webhook with the webhook URL. Optionally limit it to an environment and secret path. +4. Paste the secret into the webhook's secret key field. The secret is required: Infisical only signs webhooks that have one, and the endpoint rejects unsigned deliveries. +5. Send a test event from Infisical, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/intercom.mdx b/docs/webhooks/providers/intercom.mdx new file mode 100644 index 00000000000..510c5be02a7 --- /dev/null +++ b/docs/webhooks/providers/intercom.mdx @@ -0,0 +1,41 @@ +--- +title: "Intercom webhooks" +sidebarTitle: "Intercom" +description: "Receive Intercom webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Intercom, and how to set the signing credential." +--- + +**`webhooks.intercom()` verifies Intercom's signature on every request, so subscribers only receive genuine Intercom events.** + +```ts /trigger/intercom.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const intercom = webhooks.endpoint.define({ + id: "intercom", + source: webhooks.intercom(), +}); + +export const intercomEvents = webhook({ + id: "intercom-events", + endpoint: intercom, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.topic`. + +| | | +| --- | --- | +| Source | `webhooks.intercom()` | +| Verification | HMAC-SHA1 in `x-hub-signature` | +| Credential | Signing secret you generate on Trigger.dev, or one issued by Intercom | +| Event type | `event.topic` | +| Intercom docs | [Intercom webhook docs](https://developers.intercom.com/docs/references/webhooks/webhook-models) | + +## Set up Intercom + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as a webhook in Intercom and select the events your subscribers need. See Intercom's [webhook docs](https://developers.intercom.com/docs/references/webhooks/webhook-models) for where its webhook settings are. +3. If Intercom shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Intercom asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Intercom. +4. Send a test event from Intercom, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/jira.mdx b/docs/webhooks/providers/jira.mdx new file mode 100644 index 00000000000..522747f6f1e --- /dev/null +++ b/docs/webhooks/providers/jira.mdx @@ -0,0 +1,41 @@ +--- +title: "Jira webhooks" +sidebarTitle: "Jira" +description: "Receive Jira webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Jira, and how to set the signing credential." +--- + +**`webhooks.jira()` verifies Jira's signature on every request, so subscribers only receive genuine Jira events.** + +```ts /trigger/jira.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const jira = webhooks.endpoint.define({ + id: "jira", + source: webhooks.jira(), +}); + +export const jiraEvents = webhook({ + id: "jira-events", + endpoint: jira, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.webhookEvent`. + +| | | +| --- | --- | +| Source | `webhooks.jira()` | +| Verification | HMAC-SHA256 in `x-hub-signature` | +| Credential | Signing secret you generate on Trigger.dev, or one issued by Jira | +| Event type | `event.webhookEvent` | +| Jira docs | [Jira webhook docs](https://developer.atlassian.com/cloud/jira/platform/webhooks/) | + +## Set up Jira + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as a webhook in Jira and select the events your subscribers need. See Jira's [webhook docs](https://developer.atlassian.com/cloud/jira/platform/webhooks/) for where its webhook settings are. +3. If Jira shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Jira asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Jira. +4. Send a test event from Jira, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/langfuse.mdx b/docs/webhooks/providers/langfuse.mdx new file mode 100644 index 00000000000..8486bdd8016 --- /dev/null +++ b/docs/webhooks/providers/langfuse.mdx @@ -0,0 +1,40 @@ +--- +title: "Langfuse webhooks" +sidebarTitle: "Langfuse" +description: "Receive Langfuse webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Langfuse, and how to set the signing credential." +--- + +**`webhooks.langfuse()` verifies Langfuse's signature on every request, so subscribers only receive genuine Langfuse events.** + +```ts /trigger/langfuse.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const langfuse = webhooks.endpoint.define({ + id: "langfuse", + source: webhooks.langfuse(), +}); + +export const langfuseEvents = webhook({ + id: "langfuse-events", + endpoint: langfuse, + filter: "event.type == 'prompt-version' && event.action == 'created'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.langfuse()` | +| Verification | HMAC-SHA256 in `x-langfuse-signature` | +| Credential | Signing secret issued by Langfuse | +| Event type | `event.type` | +| Langfuse docs | [Langfuse webhook docs](https://langfuse.com/docs/prompt-management/features/webhooks-slack-integrations) | + +## Set up Langfuse + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. In the Langfuse project, go to **Prompts > Automations > Create Automation**. Choose the prompt version event and the actions (created, updated, deleted) your subscribers need, and set the request URL to the webhook URL. +3. Copy the signing secret Langfuse shows (it starts with `lf-whsec_`), then choose **Set signing secret** on the Trigger.dev endpoint. +4. Send a test event from Langfuse, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/linear.mdx b/docs/webhooks/providers/linear.mdx new file mode 100644 index 00000000000..eb582f8ffc5 --- /dev/null +++ b/docs/webhooks/providers/linear.mdx @@ -0,0 +1,45 @@ +--- +title: "Linear webhooks" +sidebarTitle: "Linear" +description: "Receive Linear webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Linear, and how to set the signing credential." +--- + +**`webhooks.linear()` verifies Linear's signature on every request, so subscribers only receive genuine Linear events.** + +```ts /trigger/linear.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const linear = webhooks.endpoint.define({ + id: "linear", + source: webhooks.linear(), +}); + +export const linearEvents = webhook({ + id: "linear-events", + endpoint: linear, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.type`. + +| | | +| --- | --- | +| Source | `webhooks.linear()` | +| Verification | HMAC-SHA256 in `linear-signature` | +| Credential | Signing secret you generate on Trigger.dev, or one issued by Linear | +| Event type | `event.type` | +| Linear docs | [Linear webhook docs](https://linear.app/developers/webhooks) | + +## Set up Linear + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as a webhook in Linear and select the events your subscribers need. See Linear's [webhook docs](https://linear.app/developers/webhooks) for where its webhook settings are. +3. If Linear shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Linear asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Linear. +4. Send a test event from Linear, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. + +## Build a Linear agent + +To work issues inside Linear's agent session UI, use the `linear()` connector from `@trigger.dev/linear`. See [Linear agents](/webhooks/linear). diff --git a/docs/webhooks/providers/loops.mdx b/docs/webhooks/providers/loops.mdx new file mode 100644 index 00000000000..74b52877f4b --- /dev/null +++ b/docs/webhooks/providers/loops.mdx @@ -0,0 +1,41 @@ +--- +title: "Loops webhooks" +sidebarTitle: "Loops" +description: "Receive Loops webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Loops, and how to set the signing credential." +--- + +**`webhooks.loops()` verifies Loops's signature on every request, so subscribers only receive genuine Loops events.** + +```ts /trigger/loops.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const loops = webhooks.endpoint.define({ + id: "loops", + source: webhooks.loops(), +}); + +export const loopsEvents = webhook({ + id: "loops-events", + endpoint: loops, + filter: "event.eventName == 'email.delivered'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.loops()` | +| Verification | Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`) | +| Credential | Signing secret issued by Loops | +| Event type | `event.eventName` | +| Loops docs | [Loops webhook docs](https://loops.so/docs/webhooks) | + +## Set up Loops + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. In Loops, go to **Settings > Webhooks**, add the webhook URL as the endpoint, and select the events your subscribers need. +3. Copy the endpoint's signing secret (it starts with `whsec_`), then choose **Set signing secret** on the Trigger.dev endpoint. +4. Send a `testing.testEvent` from the Loops settings page to confirm delivery. +5. Send a test event from Loops, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/metronome.mdx b/docs/webhooks/providers/metronome.mdx new file mode 100644 index 00000000000..f21bd02f13c --- /dev/null +++ b/docs/webhooks/providers/metronome.mdx @@ -0,0 +1,42 @@ +--- +title: "Metronome webhooks" +sidebarTitle: "Metronome" +description: "Receive Metronome webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Metronome, and how to set the signing credential." +--- + +**`webhooks.metronome()` verifies Metronome's signature on every request, so subscribers only receive genuine Metronome events.** + +```ts /trigger/metronome.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const metronome = webhooks.endpoint.define({ + id: "metronome", + source: webhooks.metronome(), +}); + +export const metronomeEvents = webhook({ + id: "metronome-events", + endpoint: metronome, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.type`. + +| | | +| --- | --- | +| Source | `webhooks.metronome()` | +| Verification | HMAC-SHA256 in `metronome-webhook-signature` | +| Credential | Signing secret issued by Metronome | +| Event type | `event.type` | +| Metronome docs | [Metronome webhook docs](https://docs.metronome.com/guides/platform-configuration/setup-webhooks) | + +## Set up Metronome + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. In the Metronome app, go to **Developer > Notifications > Webhooks > Add** and enter the webhook URL. +3. Copy the webhook's secret key, then choose **Set signing secret** on the Trigger.dev endpoint. +4. Create the notifications your subscribers need, such as a low credit balance alert, under **Developer > Notifications > Create Notification**. +5. Send a test event from Metronome, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/mux.mdx b/docs/webhooks/providers/mux.mdx new file mode 100644 index 00000000000..f1b08c441ab --- /dev/null +++ b/docs/webhooks/providers/mux.mdx @@ -0,0 +1,40 @@ +--- +title: "Mux webhooks" +sidebarTitle: "Mux" +description: "Receive Mux webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Mux, and how to set the signing credential." +--- + +**`webhooks.mux()` verifies Mux's signature on every request, so subscribers only receive genuine Mux events.** + +```ts /trigger/mux.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const mux = webhooks.endpoint.define({ + id: "mux", + source: webhooks.mux(), +}); + +export const muxEvents = webhook({ + id: "mux-events", + endpoint: mux, + filter: "event.type == 'video.asset.ready'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.mux()` | +| Verification | HMAC-SHA256 in `mux-signature` | +| Credential | Signing secret issued by Mux | +| Event type | `event.type` | +| Mux docs | [Mux webhook docs](https://www.mux.com/docs/core/verify-webhook-signatures) | + +## Set up Mux + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. In the [Mux webhook settings](https://dashboard.mux.com/settings/webhooks), select the environment your app uses and add the webhook URL. Mux sends every event in that environment. +3. Copy that webhook's signing secret, then choose **Set signing secret** on the Trigger.dev endpoint. +4. Send a test event from Mux, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/notion.mdx b/docs/webhooks/providers/notion.mdx new file mode 100644 index 00000000000..52152bc29fc --- /dev/null +++ b/docs/webhooks/providers/notion.mdx @@ -0,0 +1,40 @@ +--- +title: "Notion webhooks" +sidebarTitle: "Notion" +description: "Receive Notion webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Notion, and how to set the signing credential." +--- + +**`webhooks.notion()` verifies Notion's signature on every request, so subscribers only receive genuine Notion events.** + +```ts /trigger/notion.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const notion = webhooks.endpoint.define({ + id: "notion", + source: webhooks.notion(), +}); + +export const notionEvents = webhook({ + id: "notion-events", + endpoint: notion, + filter: "event.type == 'page.created'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.notion()` | +| Verification | HMAC-SHA256 in `x-notion-signature` | +| Credential | Signing secret issued by Notion | +| Event type | `event.type` | +| Notion docs | [Notion webhook docs](https://developers.notion.com/reference/webhooks) | + +## Set up Notion + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as a webhook in Notion and select the events your subscribers need. See Notion's [webhook docs](https://developers.notion.com/reference/webhooks) for where its webhook settings are. +3. Copy the signing secret Notion shows for the webhook, then choose **Set signing secret** on the Trigger.dev endpoint. +4. Send a test event from Notion, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/openai.mdx b/docs/webhooks/providers/openai.mdx new file mode 100644 index 00000000000..9e75d56de47 --- /dev/null +++ b/docs/webhooks/providers/openai.mdx @@ -0,0 +1,40 @@ +--- +title: "OpenAI webhooks" +sidebarTitle: "OpenAI" +description: "Receive OpenAI webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in OpenAI, and how to set the signing credential." +--- + +**`webhooks.openai()` verifies OpenAI's signature on every request, so subscribers only receive genuine OpenAI events.** + +```ts /trigger/openai.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const openai = webhooks.endpoint.define({ + id: "openai", + source: webhooks.openai(), +}); + +export const openaiEvents = webhook({ + id: "openai-events", + endpoint: openai, + filter: "event.type == 'batch.completed'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.openai()` | +| Verification | Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`) | +| Credential | Signing secret issued by OpenAI | +| Event type | `event.type` | +| OpenAI docs | [OpenAI webhook docs](https://platform.openai.com/docs/guides/webhooks) | + +## Set up OpenAI + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as an endpoint in OpenAI's webhook settings and subscribe it to the event types your subscribers need. +3. Copy the endpoint's signing secret (it starts with `whsec_`), then choose **Set signing secret** on the Trigger.dev endpoint. +4. Send a test event from OpenAI, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/pagerduty.mdx b/docs/webhooks/providers/pagerduty.mdx new file mode 100644 index 00000000000..14b4ae20180 --- /dev/null +++ b/docs/webhooks/providers/pagerduty.mdx @@ -0,0 +1,40 @@ +--- +title: "PagerDuty webhooks" +sidebarTitle: "PagerDuty" +description: "Receive PagerDuty webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in PagerDuty, and how to set the signing credential." +--- + +**`webhooks.pagerduty()` verifies PagerDuty's signature on every request, so subscribers only receive genuine PagerDuty events.** + +```ts /trigger/pagerduty.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const pagerduty = webhooks.endpoint.define({ + id: "pagerduty", + source: webhooks.pagerduty(), +}); + +export const pagerdutyEvents = webhook({ + id: "pagerduty-events", + endpoint: pagerduty, + filter: "event.event.event_type == 'incident.triggered'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.pagerduty()` | +| Verification | HMAC-SHA256 in `x-pagerduty-signature` | +| Credential | Signing secret you generate on Trigger.dev, or one issued by PagerDuty | +| Event type | `event.event.event_type` | +| PagerDuty docs | [PagerDuty webhook docs](https://developer.pagerduty.com/docs/webhooks/webhook-signatures/) | + +## Set up PagerDuty + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as a webhook in PagerDuty and select the events your subscribers need. See PagerDuty's [webhook docs](https://developer.pagerduty.com/docs/webhooks/webhook-signatures/) for where its webhook settings are. +3. If PagerDuty shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If PagerDuty asks you for a secret, choose **Generate secret** on the endpoint and paste the value into PagerDuty. +4. Send a test event from PagerDuty, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/plain.mdx b/docs/webhooks/providers/plain.mdx new file mode 100644 index 00000000000..4c10a6260c3 --- /dev/null +++ b/docs/webhooks/providers/plain.mdx @@ -0,0 +1,41 @@ +--- +title: "Plain webhooks" +sidebarTitle: "Plain" +description: "Receive Plain webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Plain, and how to set the signing credential." +--- + +**`webhooks.plain()` verifies Plain's signature on every request, so subscribers only receive genuine Plain events.** + +```ts /trigger/plain.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const plain = webhooks.endpoint.define({ + id: "plain", + source: webhooks.plain(), +}); + +export const plainEvents = webhook({ + id: "plain-events", + endpoint: plain, + filter: "event.type == 'thread.thread_created'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.plain()` | +| Verification | HMAC-SHA256 in `plain-request-signature` | +| Credential | Signing secret issued by Plain | +| Event type | `event.type` | +| Plain docs | [Plain webhook docs](https://www.plain.com/docs/api-reference/webhooks) | + +## Set up Plain + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. As a workspace admin, view or generate the request signing secret under **Settings > Request signing**. It is one secret for the whole workspace, so read the existing one if other webhook targets use it. +3. Choose **Set signing secret** on the Trigger.dev endpoint and paste it. +4. Add the target under **Settings > Webhooks > Add webhook target**, with the webhook URL and the events your subscribers need. +5. Send a test event from Plain, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/planetscale.mdx b/docs/webhooks/providers/planetscale.mdx new file mode 100644 index 00000000000..a9feb6a9076 --- /dev/null +++ b/docs/webhooks/providers/planetscale.mdx @@ -0,0 +1,41 @@ +--- +title: "PlanetScale webhooks" +sidebarTitle: "PlanetScale" +description: "Receive PlanetScale webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in PlanetScale, and how to set the signing credential." +--- + +**`webhooks.planetscale()` verifies PlanetScale's signature on every request, so subscribers only receive genuine PlanetScale events.** + +```ts /trigger/planetscale.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const planetscale = webhooks.endpoint.define({ + id: "planetscale", + source: webhooks.planetscale(), +}); + +export const planetscaleEvents = webhook({ + id: "planetscale-events", + endpoint: planetscale, + filter: "event.event == 'branch.ready'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.planetscale()` | +| Verification | HMAC-SHA256 in `x-planetscale-signature` | +| Credential | Signing secret issued by PlanetScale | +| Event type | `event.event` | +| PlanetScale docs | [PlanetScale webhook docs](https://planetscale.com/docs/api/webhooks) | + +## Set up PlanetScale + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Select the database in PlanetScale, then **Settings > Webhooks > Add webhook**. Enter the webhook URL and select the events your subscribers need. This needs the database administrator role. +3. In the webhook's menu, choose **Show secret**, copy it, and choose **Set signing secret** on the Trigger.dev endpoint. +4. Choose **Test webhook** in the same menu to send a `webhook.test` event. +5. Send a test event from PlanetScale, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/recall-ai.mdx b/docs/webhooks/providers/recall-ai.mdx new file mode 100644 index 00000000000..5b662e1c0e9 --- /dev/null +++ b/docs/webhooks/providers/recall-ai.mdx @@ -0,0 +1,41 @@ +--- +title: "Recall.ai webhooks" +sidebarTitle: "Recall.ai" +description: "Receive Recall.ai webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Recall.ai, and how to set the signing credential." +--- + +**`webhooks.recallai()` verifies Recall.ai's signature on every request, so subscribers only receive genuine Recall.ai events.** + +```ts /trigger/recall-ai.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const recallai = webhooks.endpoint.define({ + id: "recall-ai", + source: webhooks.recallai(), +}); + +export const recallaiEvents = webhook({ + id: "recall-ai-events", + endpoint: recallai, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event`. + +| | | +| --- | --- | +| Source | `webhooks.recallai()` | +| Verification | Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`) | +| Credential | Signing secret issued by Recall.ai | +| Event type | `event.event` | +| Recall.ai docs | [Recall.ai webhook docs](https://docs.recall.ai/docs/authenticating-requests-from-recallai) | + +## Set up Recall.ai + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as an endpoint in Recall.ai's webhook settings and subscribe it to the event types your subscribers need. +3. Copy the endpoint's signing secret (it starts with `whsec_`), then choose **Set signing secret** on the Trigger.dev endpoint. +4. Send a test event from Recall.ai, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/replicate.mdx b/docs/webhooks/providers/replicate.mdx new file mode 100644 index 00000000000..5fcf0a5dc86 --- /dev/null +++ b/docs/webhooks/providers/replicate.mdx @@ -0,0 +1,41 @@ +--- +title: "Replicate webhooks" +sidebarTitle: "Replicate" +description: "Receive Replicate webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Replicate, and how to set the signing credential." +--- + +**`webhooks.replicate()` verifies Replicate's signature on every request, so subscribers only receive genuine Replicate events.** + +```ts /trigger/replicate.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const replicate = webhooks.endpoint.define({ + id: "replicate", + source: webhooks.replicate(), +}); + +export const replicateEvents = webhook({ + id: "replicate-events", + endpoint: replicate, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.status`. + +| | | +| --- | --- | +| Source | `webhooks.replicate()` | +| Verification | Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`) | +| Credential | Signing secret issued by Replicate | +| Event type | `event.status` | +| Replicate docs | [Replicate webhook docs](https://replicate.com/docs/topics/webhooks/verify-webhook) | + +## Set up Replicate + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as an endpoint in Replicate's webhook settings and subscribe it to the event types your subscribers need. +3. Copy the endpoint's signing secret (it starts with `whsec_`), then choose **Set signing secret** on the Trigger.dev endpoint. +4. Send a test event from Replicate, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/resend.mdx b/docs/webhooks/providers/resend.mdx new file mode 100644 index 00000000000..d296e15230c --- /dev/null +++ b/docs/webhooks/providers/resend.mdx @@ -0,0 +1,44 @@ +--- +title: "Resend webhooks" +sidebarTitle: "Resend" +description: "Receive Resend webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Resend, and how to set the signing credential." +--- + +**`webhooks.resend()` verifies Resend's signature on every request, so subscribers only receive genuine Resend events.** + +```ts /trigger/resend.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const resend = webhooks.endpoint.define({ + id: "resend", + source: webhooks.resend(), +}); + +export const resendEvents = webhook({ + id: "resend-events", + endpoint: resend, + filter: "event.type == 'email.delivered'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.resend()` | +| Verification | Svix (`svix-id`, `svix-timestamp`, `svix-signature`) | +| Credential | Signing secret issued by Resend | +| Event type | `event.type` | +| Resend docs | [Resend webhook docs](https://resend.com/docs/dashboard/webhooks/introduction) | + +## Set up Resend + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as an endpoint in Resend's webhook settings and subscribe it to the event types your subscribers need. +3. Copy the endpoint's signing secret (it starts with `whsec_`), then choose **Set signing secret** on the Trigger.dev endpoint. +4. Send a test event from Resend, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. + +## Example project + +The [Resend email agent example](/guides/example-projects/resend-email-agent) drafts replies to a Resend inbox from these webhooks and waits for approval in Slack before sending. diff --git a/docs/webhooks/providers/retell.mdx b/docs/webhooks/providers/retell.mdx new file mode 100644 index 00000000000..6ed91d2c919 --- /dev/null +++ b/docs/webhooks/providers/retell.mdx @@ -0,0 +1,41 @@ +--- +title: "Retell AI webhooks" +sidebarTitle: "Retell AI" +description: "Receive Retell AI webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Retell AI, and how to set the signing credential." +--- + +**`webhooks.retell()` verifies Retell AI's signature on every request, so subscribers only receive genuine Retell AI events.** + +```ts /trigger/retell.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const retell = webhooks.endpoint.define({ + id: "retell", + source: webhooks.retell(), +}); + +export const retellEvents = webhook({ + id: "retell-events", + endpoint: retell, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event`. + +| | | +| --- | --- | +| Source | `webhooks.retell()` | +| Verification | HMAC-SHA256 in `x-retell-signature` | +| Credential | Signing secret issued by Retell AI | +| Event type | `event.event` | +| Retell AI docs | [Retell AI webhook docs](https://docs.retellai.com/features/secure-webhook) | + +## Set up Retell AI + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as a webhook in Retell AI and select the events your subscribers need. See Retell AI's [webhook docs](https://docs.retellai.com/features/secure-webhook) for where its webhook settings are. +3. Copy the signing secret Retell AI shows for the webhook, then choose **Set signing secret** on the Trigger.dev endpoint. +4. Send a test event from Retell AI, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/sentry.mdx b/docs/webhooks/providers/sentry.mdx new file mode 100644 index 00000000000..6eae8a2e4fe --- /dev/null +++ b/docs/webhooks/providers/sentry.mdx @@ -0,0 +1,41 @@ +--- +title: "Sentry webhooks" +sidebarTitle: "Sentry" +description: "Receive Sentry webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Sentry, and how to set the signing credential." +--- + +**`webhooks.sentry()` verifies Sentry's signature on every request, so subscribers only receive genuine Sentry events.** + +```ts /trigger/sentry.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const sentry = webhooks.endpoint.define({ + id: "sentry", + source: webhooks.sentry(), +}); + +export const sentryEvents = webhook({ + id: "sentry-events", + endpoint: sentry, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `header.sentry-hook-resource`. + +| | | +| --- | --- | +| Source | `webhooks.sentry()` | +| Verification | HMAC-SHA256 in `sentry-hook-signature` | +| Credential | Signing secret you generate on Trigger.dev, or one issued by Sentry | +| Event type | `header.sentry-hook-resource` | +| Sentry docs | [Sentry webhook docs](https://docs.sentry.io/product/integrations/integration-platform/webhooks/) | + +## Set up Sentry + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as a webhook in Sentry and select the events your subscribers need. See Sentry's [webhook docs](https://docs.sentry.io/product/integrations/integration-platform/webhooks/) for where its webhook settings are. +3. If Sentry shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Sentry asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Sentry. +4. Send a test event from Sentry, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/shopify.mdx b/docs/webhooks/providers/shopify.mdx new file mode 100644 index 00000000000..8d5fe56dead --- /dev/null +++ b/docs/webhooks/providers/shopify.mdx @@ -0,0 +1,49 @@ +--- +title: "Shopify webhooks" +sidebarTitle: "Shopify" +description: "Receive Shopify webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Shopify, and how to set the signing credential." +--- + +**`webhooks.shopify()` verifies Shopify's signature on every request, so subscribers only receive genuine Shopify events.** + +```ts /trigger/shopify.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const shopify = webhooks.endpoint.define({ + id: "shopify", + source: webhooks.shopify(), +}); + +export const shopifyEvents = webhook({ + id: "shopify-events", + endpoint: shopify, + filter: "header.x-shopify-topic == 'orders/create'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.shopify()` | +| Verification | HMAC-SHA256 in `x-shopify-hmac-sha256` | +| Credential | Signing secret issued by Shopify | +| Event type | `header.x-shopify-topic` | +| Shopify docs | [Shopify webhook docs](https://shopify.dev/docs/apps/build/webhooks/verify-deliveries) | + +## Set up Shopify + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. For an app, add a subscription to `shopify.app.toml` and run `shopify app deploy`: + + ```toml shopify.app.toml + [[webhooks.subscriptions]] + topics = ["orders/create"] + uri = "" + ``` + + Or create it with the Admin API's `webhookSubscriptionCreate` mutation. Use the JSON format. +3. Shopify signs app webhooks with the app's client secret, which is in the app's settings in the Shopify Dev Dashboard. Choose **Set signing secret** on the Trigger.dev endpoint and paste it. +4. For a store without an app, add the webhook under **Settings > Notifications > Webhooks** in the store admin, and use the signing key shown on that page instead. +5. Send a test event from Shopify, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/slack.mdx b/docs/webhooks/providers/slack.mdx new file mode 100644 index 00000000000..9909d66a1cd --- /dev/null +++ b/docs/webhooks/providers/slack.mdx @@ -0,0 +1,47 @@ +--- +title: "Slack webhooks" +sidebarTitle: "Slack" +description: "Receive Slack webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Slack, and how to set the signing credential." +--- + +**`webhookSource()` from `@trigger.dev/slack` verifies Slack's signature on every request, so subscribers only receive genuine Slack events.** + +```ts /trigger/slack.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; +import { webhookSource } from "@trigger.dev/slack"; + +export const slack = webhooks.endpoint.define({ + id: "slack", + source: webhookSource(), +}); + +export const slackEvents = webhook({ + id: "slack-events", + endpoint: slack, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event.type`. + +| | | +| --- | --- | +| Source | `webhookSource()` from `@trigger.dev/slack` | +| Verification | HMAC-SHA256 in `x-slack-signature`, with a timestamp tolerance | +| Credential | Signing secret issued by Slack | +| Event type | `event.event.type` | +| Slack docs | [Slack webhook docs](https://docs.slack.dev/authentication/verifying-requests-from-slack/) | + +## Set up Slack + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. In your Slack app's settings, set the **Event Subscriptions** request URL to the webhook URL and subscribe to the bot events your subscribers need. +3. Copy the app's **Signing Secret** from **Basic Information > App Credentials**, then choose **Set signing secret** on the Trigger.dev endpoint. +4. Back on the Event Subscriptions page, choose **Verify**. Slack's `url_verification` challenge is answered by the endpoint once the secret is set. +5. Send a test event from Slack, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. + +## Build a Slack agent + +To answer messages in Slack with a `chat.agent`, use the `slack()` connector on the same endpoint. It handles streaming replies, status updates and approvals. See [Slack agents](/webhooks/slack). diff --git a/docs/webhooks/providers/square.mdx b/docs/webhooks/providers/square.mdx new file mode 100644 index 00000000000..554b1ce3d9e --- /dev/null +++ b/docs/webhooks/providers/square.mdx @@ -0,0 +1,40 @@ +--- +title: "Square webhooks" +sidebarTitle: "Square" +description: "Receive Square webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Square, and how to set the signing credential." +--- + +**`webhooks.square()` verifies Square's signature on every request, so subscribers only receive genuine Square events.** + +```ts /trigger/square.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const square = webhooks.endpoint.define({ + id: "square", + source: webhooks.square(), +}); + +export const squareEvents = webhook({ + id: "square-events", + endpoint: square, + filter: "event.type == 'payment.created'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.square()` | +| Verification | HMAC-SHA256 in `x-square-hmacsha256-signature` | +| Credential | Signing secret issued by Square | +| Event type | `event.type` | +| Square docs | [Square webhook docs](https://developer.squareup.com/docs/webhooks/step3validate) | + +## Set up Square + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as a webhook in Square and select the events your subscribers need. See Square's [webhook docs](https://developer.squareup.com/docs/webhooks/step3validate) for where its webhook settings are. +3. Copy the signing secret Square shows for the webhook, then choose **Set signing secret** on the Trigger.dev endpoint. +4. Send a test event from Square, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/stripe.mdx b/docs/webhooks/providers/stripe.mdx new file mode 100644 index 00000000000..d1587a72f98 --- /dev/null +++ b/docs/webhooks/providers/stripe.mdx @@ -0,0 +1,61 @@ +--- +title: "Stripe webhooks" +sidebarTitle: "Stripe" +description: "Receive Stripe webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Stripe, and how to set the signing credential." +--- + +**`webhooks.stripe()` verifies Stripe's signature on every request, so subscribers only receive genuine Stripe events.** + +```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, + filter: "event.type == 'checkout.session.completed'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.stripe()` | +| Verification | HMAC-SHA256 in `stripe-signature`, with a timestamp tolerance | +| Credential | Signing secret issued by Stripe | +| Event type | `event.type` | +| Stripe docs | [Stripe webhook docs](https://docs.stripe.com/webhooks) | + +## Set up Stripe + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Create the webhook endpoint with the Stripe CLI or API, not the Dashboard, so you can read the signing secret from the response: + + ```bash + stripe webhook_endpoints create -d url="" -d "enabled_events[]=checkout.session.completed" + ``` + + The response's `secret` field is the signing secret; Stripe only returns it when the endpoint is created. +3. Choose **Set signing secret** on the Trigger.dev endpoint and paste the secret. +4. Use a test mode key for dev and staging environments and a live mode key for production. +5. Send a test event from Stripe, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. + +## Typing the event + +`webhooks.stripe()` provides a default event shape. For the full Stripe types, install the `stripe` package and pass `Stripe.Event`: + +```ts /trigger/stripe.ts +import type Stripe from "stripe"; +import { webhooks } from "@trigger.dev/sdk"; + +export const stripe = webhooks.endpoint.define({ + id: "stripe", + source: webhooks.stripe(), +}); +``` diff --git a/docs/webhooks/providers/supabase.mdx b/docs/webhooks/providers/supabase.mdx new file mode 100644 index 00000000000..58cb562de89 --- /dev/null +++ b/docs/webhooks/providers/supabase.mdx @@ -0,0 +1,41 @@ +--- +title: "Supabase webhooks" +sidebarTitle: "Supabase" +description: "Receive Supabase webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Supabase, and how to set the signing credential." +--- + +**`webhooks.supabase()` checks a shared secret on every request, because Supabase database webhooks aren't signed.** + +```ts /trigger/supabase.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const supabase = webhooks.endpoint.define({ + id: "supabase", + source: webhooks.supabase(), +}); + +export const supabaseEvents = webhook({ + id: "supabase-events", + endpoint: supabase, + filter: "event.type == 'INSERT' && event.table == 'orders'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.supabase()` | +| Verification | Shared secret as `Authorization: Bearer` | +| Credential | Secret you generate on Trigger.dev | +| Event type | `event.type` | +| Supabase docs | [Supabase webhook docs](https://supabase.com/docs/guides/database/webhooks) | + +## Set up Supabase + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Choose **Generate secret** on the Trigger.dev endpoint and copy the value. Supabase database webhooks aren't signed, so the endpoint checks this shared secret instead. +3. On the **Database Webhooks** page of the Supabase dashboard, create a webhook on the table and events (`INSERT`, `UPDATE`, `DELETE`) your subscribers need, with type **HTTP Request**, method `POST`, and the webhook URL. +4. Under **HTTP Headers**, add `Authorization` with the value `Bearer `. +5. Insert a row into the table, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/tailscale.mdx b/docs/webhooks/providers/tailscale.mdx new file mode 100644 index 00000000000..143808abbe5 --- /dev/null +++ b/docs/webhooks/providers/tailscale.mdx @@ -0,0 +1,44 @@ +--- +title: "Tailscale webhooks" +sidebarTitle: "Tailscale" +description: "Receive Tailscale webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Tailscale, and how to set the signing credential." +--- + +**`webhooks.tailscale()` verifies Tailscale's signature on every request, so subscribers only receive genuine Tailscale events.** + +```ts /trigger/tailscale.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const tailscale = webhooks.endpoint.define({ + id: "tailscale", + source: webhooks.tailscale(), +}); + +export const tailscaleEvents = webhook({ + id: "tailscale-events", + endpoint: tailscale, + filter: "event any ( type == 'nodeCreated' )", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.tailscale()` | +| Verification | HMAC-SHA256 in `tailscale-webhook-signature` | +| Credential | Signing secret issued by Tailscale | +| Tailscale docs | [Tailscale webhook docs](https://tailscale.com/kb/1213/webhooks) | + +## Set up Tailscale + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. On the **Webhooks** page of the Tailscale admin console, select **Add endpoint**, enter the webhook URL, and choose the events your subscribers need. This needs the Owner, Admin, Network admin or IT admin role. +3. Tailscale shows the webhook secret once, right after the endpoint is added. Copy it then, and choose **Set signing secret** on the Trigger.dev endpoint. +4. Use the endpoint's menu, **Test endpoint > Send test event**, to confirm delivery. +5. Send a test event from Tailscale, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. + +## Batched events + +Each request body is a JSON array of events, and Tailscale can batch several into one request. Filters match an event anywhere in the array with `event any ( ... )`, and a handler should process every event in the array. diff --git a/docs/webhooks/providers/typeform.mdx b/docs/webhooks/providers/typeform.mdx new file mode 100644 index 00000000000..3235ac2b06c --- /dev/null +++ b/docs/webhooks/providers/typeform.mdx @@ -0,0 +1,41 @@ +--- +title: "Typeform webhooks" +sidebarTitle: "Typeform" +description: "Receive Typeform webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Typeform, and how to set the signing credential." +--- + +**`webhooks.typeform()` verifies Typeform's signature on every request, so subscribers only receive genuine Typeform events.** + +```ts /trigger/typeform.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const typeform = webhooks.endpoint.define({ + id: "typeform", + source: webhooks.typeform(), +}); + +export const typeformEvents = webhook({ + id: "typeform-events", + endpoint: typeform, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event_type`. + +| | | +| --- | --- | +| Source | `webhooks.typeform()` | +| Verification | HMAC-SHA256 in `typeform-signature` | +| Credential | Signing secret you generate on Trigger.dev, or one issued by Typeform | +| Event type | `event.event_type` | +| Typeform docs | [Typeform webhook docs](https://www.typeform.com/developers/webhooks/secure-your-webhooks/) | + +## Set up Typeform + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as a webhook in Typeform and select the events your subscribers need. See Typeform's [webhook docs](https://www.typeform.com/developers/webhooks/secure-your-webhooks/) for where its webhook settings are. +3. If Typeform shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Typeform asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Typeform. +4. Send a test event from Typeform, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/vapi.mdx b/docs/webhooks/providers/vapi.mdx new file mode 100644 index 00000000000..f32cf21dbf0 --- /dev/null +++ b/docs/webhooks/providers/vapi.mdx @@ -0,0 +1,41 @@ +--- +title: "Vapi webhooks" +sidebarTitle: "Vapi" +description: "Receive Vapi webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Vapi, and how to set the signing credential." +--- + +**`webhooks.vapi()` verifies Vapi's signature on every request, so subscribers only receive genuine Vapi events.** + +```ts /trigger/vapi.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const vapi = webhooks.endpoint.define({ + id: "vapi", + source: webhooks.vapi(), +}); + +export const vapiEvents = webhook({ + id: "vapi-events", + endpoint: vapi, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.message.type`. + +| | | +| --- | --- | +| Source | `webhooks.vapi()` | +| Verification | HMAC-SHA256 in `x-vapi-signature` | +| Credential | Signing secret you generate on Trigger.dev, or one issued by Vapi | +| Event type | `event.message.type` | +| Vapi docs | [Vapi webhook docs](https://docs.vapi.ai/server-url/server-authentication) | + +## Set up Vapi + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as a webhook in Vapi and select the events your subscribers need. See Vapi's [webhook docs](https://docs.vapi.ai/server-url/server-authentication) for where its webhook settings are. +3. If Vapi shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Vapi asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Vapi. +4. Send a test event from Vapi, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/vercel.mdx b/docs/webhooks/providers/vercel.mdx new file mode 100644 index 00000000000..cb370c11f42 --- /dev/null +++ b/docs/webhooks/providers/vercel.mdx @@ -0,0 +1,40 @@ +--- +title: "Vercel webhooks" +sidebarTitle: "Vercel" +description: "Receive Vercel webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Vercel, and how to set the signing credential." +--- + +**`webhooks.vercel()` verifies Vercel's signature on every request, so subscribers only receive genuine Vercel events.** + +```ts /trigger/vercel.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const vercel = webhooks.endpoint.define({ + id: "vercel", + source: webhooks.vercel(), +}); + +export const vercelEvents = webhook({ + id: "vercel-events", + endpoint: vercel, + filter: "event.type == 'deployment.succeeded'", + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.vercel()` | +| Verification | HMAC-SHA1 in `x-vercel-signature` | +| Credential | Signing secret you generate on Trigger.dev, or one issued by Vercel | +| Event type | `event.type` | +| Vercel docs | [Vercel webhook docs](https://vercel.com/docs/webhooks) | + +## Set up Vercel + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as a webhook in Vercel and select the events your subscribers need. See Vercel's [webhook docs](https://vercel.com/docs/webhooks) for where its webhook settings are. +3. If Vercel shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Vercel asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Vercel. +4. Send a test event from Vercel, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/whatsapp.mdx b/docs/webhooks/providers/whatsapp.mdx new file mode 100644 index 00000000000..fde82c5de81 --- /dev/null +++ b/docs/webhooks/providers/whatsapp.mdx @@ -0,0 +1,39 @@ +--- +title: "WhatsApp webhooks" +sidebarTitle: "WhatsApp" +description: "Receive WhatsApp webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in WhatsApp, and how to set the signing credential." +--- + +**`webhooks.whatsapp()` verifies WhatsApp's signature on every request, so subscribers only receive genuine WhatsApp events.** + +```ts /trigger/whatsapp.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const whatsapp = webhooks.endpoint.define({ + id: "whatsapp", + source: webhooks.whatsapp(), +}); + +export const whatsappEvents = webhook({ + id: "whatsapp-events", + endpoint: whatsapp, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +| | | +| --- | --- | +| Source | `webhooks.whatsapp()` | +| Verification | HMAC-SHA256 in `x-hub-signature-256`, keyed by the App Secret | +| Credential | Signing secret issued by WhatsApp | +| WhatsApp docs | [WhatsApp webhook docs](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/set-up-webhooks/) | + +## Set up WhatsApp + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. In the Meta app dashboard, set the WhatsApp webhook's callback URL to the webhook URL. Meta verifies the URL with a GET request that needs a verify token; see [Verify a WhatsApp endpoint URL](/webhooks/connect#verify-a-whatsapp-endpoint-url). +3. Copy the app's **App Secret**, then choose **Set signing secret** on the Trigger.dev endpoint. Meta signs event deliveries with it. +4. Subscribe the webhook to the fields your subscribers need, such as `messages`. +5. Send a test event from WhatsApp, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/workos.mdx b/docs/webhooks/providers/workos.mdx new file mode 100644 index 00000000000..c30a62df9dc --- /dev/null +++ b/docs/webhooks/providers/workos.mdx @@ -0,0 +1,41 @@ +--- +title: "WorkOS webhooks" +sidebarTitle: "WorkOS" +description: "Receive WorkOS webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in WorkOS, and how to set the signing credential." +--- + +**`webhooks.workos()` verifies WorkOS's signature on every request, so subscribers only receive genuine WorkOS events.** + +```ts /trigger/workos.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const workos = webhooks.endpoint.define({ + id: "workos", + source: webhooks.workos(), +}); + +export const workosEvents = webhook({ + id: "workos-events", + endpoint: workos, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event`. + +| | | +| --- | --- | +| Source | `webhooks.workos()` | +| Verification | HMAC-SHA256 in `workos-signature` | +| Credential | Signing secret issued by WorkOS | +| Event type | `event.event` | +| WorkOS docs | [WorkOS webhook docs](https://workos.com/docs/events/data-syncing/webhooks) | + +## Set up WorkOS + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as a webhook in WorkOS and select the events your subscribers need. See WorkOS's [webhook docs](https://workos.com/docs/events/data-syncing/webhooks) for where its webhook settings are. +3. Copy the signing secret WorkOS shows for the webhook, then choose **Set signing secret** on the Trigger.dev endpoint. +4. Send a test event from WorkOS, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/zendesk.mdx b/docs/webhooks/providers/zendesk.mdx new file mode 100644 index 00000000000..144f90ad37f --- /dev/null +++ b/docs/webhooks/providers/zendesk.mdx @@ -0,0 +1,41 @@ +--- +title: "Zendesk webhooks" +sidebarTitle: "Zendesk" +description: "Receive Zendesk webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Zendesk, and how to set the signing credential." +--- + +**`webhooks.zendesk()` verifies Zendesk's signature on every request, so subscribers only receive genuine Zendesk events.** + +```ts /trigger/zendesk.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const zendesk = webhooks.endpoint.define({ + id: "zendesk", + source: webhooks.zendesk(), +}); + +export const zendeskEvents = webhook({ + id: "zendesk-events", + endpoint: zendesk, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.status`. + +| | | +| --- | --- | +| Source | `webhooks.zendesk()` | +| Verification | HMAC-SHA256 in `x-zendesk-webhook-signature` | +| Credential | Signing secret you generate on Trigger.dev, or one issued by Zendesk | +| Event type | `event.status` | +| Zendesk docs | [Zendesk webhook docs](https://developer.zendesk.com/documentation/webhooks/verifying/) | + +## Set up Zendesk + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as a webhook in Zendesk and select the events your subscribers need. See Zendesk's [webhook docs](https://developer.zendesk.com/documentation/webhooks/verifying/) for where its webhook settings are. +3. If Zendesk shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Zendesk asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Zendesk. +4. Send a test event from Zendesk, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/zoom.mdx b/docs/webhooks/providers/zoom.mdx new file mode 100644 index 00000000000..0e28924c367 --- /dev/null +++ b/docs/webhooks/providers/zoom.mdx @@ -0,0 +1,41 @@ +--- +title: "Zoom webhooks" +sidebarTitle: "Zoom" +description: "Receive Zoom webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Zoom, and how to set the signing credential." +--- + +**`webhooks.zoom()` verifies Zoom's signature on every request, so subscribers only receive genuine Zoom events.** + +```ts /trigger/zoom.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const zoom = webhooks.endpoint.define({ + id: "zoom", + source: webhooks.zoom(), +}); + +export const zoomEvents = webhook({ + id: "zoom-events", + endpoint: zoom, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event`. + +| | | +| --- | --- | +| Source | `webhooks.zoom()` | +| Verification | HMAC-SHA256 in `x-zm-signature` | +| Credential | Signing secret issued by Zoom | +| Event type | `event.event` | +| Zoom docs | [Zoom webhook docs](https://developers.zoom.us/docs/api/webhooks/) | + +## Set up Zoom + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Add the webhook URL as a webhook in Zoom and select the events your subscribers need. See Zoom's [webhook docs](https://developers.zoom.us/docs/api/webhooks/) for where its webhook settings are. +3. Copy the signing secret Zoom shows for the webhook, then choose **Set signing secret** on the Trigger.dev endpoint. +4. Send a test event from Zoom, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/public-beta.mdx b/docs/webhooks/public-beta.mdx deleted file mode 100644 index d8074998df1..00000000000 --- a/docs/webhooks/public-beta.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: "Webhooks public beta" -description: "Webhooks are available to every organization in the normal Trigger.dev release. Install the packages, see what may change before general availability, and send feedback." -sidebarTitle: "Public beta" ---- - -**Webhooks are in public beta: every organization can use them, and they ship in the normal Trigger.dev release.** Endpoints you declare sync when you deploy or run `trigger dev`, and they show up on each environment's **Webhooks** page. - -## What public beta means - -- The API may still change before general availability. We announce changes in the [changelog](https://trigger.dev/changelog). -- Webhooks are open source, so they work self-hosted too. See [Self-hosting webhooks](/self-hosting/env/webapp#webhooks) to turn them on. - -## Install the packages - -Webhooks are in `@trigger.dev/sdk` 4.8.1 and later. Install the SDK and the CLI from `@latest`: - - - -```bash npm -npm i @trigger.dev/sdk@latest -npm i -D trigger.dev@latest -``` - -```bash pnpm -pnpm add @trigger.dev/sdk@latest -pnpm add -D trigger.dev@latest -``` - -```bash bun -bun add @trigger.dev/sdk@latest -bun add -D trigger.dev@latest -``` - - - -Add the connector packages if you're building Slack or Linear agents: - - - -```bash npm -npm i @trigger.dev/slack@latest @trigger.dev/linear@latest -``` - -```bash pnpm -pnpm add @trigger.dev/slack@latest @trigger.dev/linear@latest -``` - -```bash bun -bun add @trigger.dev/slack@latest @trigger.dev/linear@latest -``` - - - -The webhook tools in the [MCP server](/mcp-introduction) come with the CLI, so a current `trigger.dev` install has them. - -## Moving from a private beta build - -If you installed from the `webhooks` npm tag, switch every Trigger.dev package to `@latest`, including `@trigger.dev/build` if your project has it. Versions like `4.8.0-webhooks.20261020092920` are older than 4.8.1. You can also remove any minimum release age exemption you added for the beta builds, and reinstall the MCP server without `--tag webhooks`. - -## Get started - -- [Overview](/webhooks/overview): endpoints, sources, and what can subscribe. -- [Connect a provider](/webhooks/connect): register the URL and signing secret, then check that events arrive. -- [Slack agents](/webhooks/slack) and [Linear agents](/webhooks/linear): turn a `chat.agent` into an agent that lives in Slack or Linear. -- [Deliveries and endpoints](/webhooks/deliveries): inspect payloads, replay deliveries, and see the runs each one started. - -## Feedback - -Send bugs, questions and ideas to [eric@trigger.dev](mailto:eric@trigger.dev). Delivery ids (`whd_...`) and run ids help us find what happened. diff --git a/docs/webhooks/quick-start.mdx b/docs/webhooks/quick-start.mdx new file mode 100644 index 00000000000..6031110ddb7 --- /dev/null +++ b/docs/webhooks/quick-start.mdx @@ -0,0 +1,127 @@ +--- +title: "Webhooks quick start" +sidebarTitle: "Quick start" +description: "Declare a hosted webhook endpoint, run it in dev, and see your first verified delivery start a task run in under 5 minutes." +--- + +Install the SDK, declare an endpoint with a subscriber, and send it a test event. By the end, a verified delivery starts a run of your task. + +This guide uses the [GitHub source](/webhooks/providers/github) because you generate its signing secret on Trigger.dev, so you don't need a GitHub account to finish it. The steps are the same for every [provider](/webhooks/providers). + + + + + +Skip this step if your project already uses Trigger.dev 4.8.1 or later. + + + +```bash npm +npx trigger.dev@latest init +``` + +```bash pnpm +pnpm dlx trigger.dev@latest init +``` + +```bash bun +bunx trigger.dev@latest init +``` + + + +To upgrade an existing project, install the SDK and CLI from `@latest`: + + + +```bash npm +npm i @trigger.dev/sdk@latest +npm i -D trigger.dev@latest +``` + +```bash pnpm +pnpm add @trigger.dev/sdk@latest +pnpm add -D trigger.dev@latest +``` + +```bash bun +bun add @trigger.dev/sdk@latest +bun add -D trigger.dev@latest +``` + + + + + + + +Create a file in your `/trigger` directory. The endpoint is the hosted URL; the subscriber is the task that runs for each event. + +```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 ({ event, headers }) => { + // GitHub sends the event name in a header + console.log("Received", headers.get("x-github-event"), event); + }, +}); +``` + + + + + + + +```bash npm +npx trigger.dev@latest dev +``` + +```bash pnpm +pnpm dlx trigger.dev@latest dev +``` + +```bash bun +bunx trigger.dev@latest dev +``` + + + +The CLI registers the endpoint, and it appears on the dev environment's **Webhooks** page with the **Signing secret** column set to **Needs secret**. + + + + + +Open the `github` endpoint and choose **Generate secret**. The column changes to **Ready**. Every delivery is rejected until an endpoint has its secret. + + + + + +Open the endpoint's **Test** tab and send the sample event. The delivery appears on the **Deliveries** tab with the `github-events` subscriber listed. Follow the link to its run to see the logged event. + + + + + +## Connect the real provider + +To receive real events, register the endpoint's **Webhook URL** and the same secret with the provider. Each [provider page](/webhooks/providers) lists where to add them. + + + + Register the URL and secret by hand or with an AI coding agent. + + + Run a subscriber only for the events it handles. + + diff --git a/docs/webhooks/sources.mdx b/docs/webhooks/sources.mdx index 330f60f8b41..64cc40cb22c 100644 --- a/docs/webhooks/sources.mdx +++ b/docs/webhooks/sources.mdx @@ -4,7 +4,7 @@ description: "Choose an endpoint's source, configure verification, and type the sidebarTitle: "Sources & verification" --- -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()`. +An endpoint's `source` defines how Trigger.dev verifies requests and types the event every subscriber receives. Choose a [built-in provider source](/webhooks/providers), such as `webhooks.stripe()` or `webhooks.firecrawl()`, or supply a verification configuration with [`webhooks.custom()`](/webhooks/custom-providers). ## Presets @@ -73,7 +73,7 @@ export const composioEvents = webhook({ -The available presets are `stripe()`, `github()`, `svix()`, `standardWebhooks()`, `square()`, and `discord()`. +The available presets are `stripe()`, `github()`, `svix()`, `standardWebhooks()`, `square()`, and `discord()`. More than 40 named providers build on the same verifiers; see [Providers](/webhooks/providers) for the full list and each provider's setup. ### Svix and Standard Webhooks @@ -86,57 +86,6 @@ The available presets are `stripe()`, `github()`, `svix()`, `standardWebhooks()` 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()` | -| Hookdeck relay (HMAC-SHA256 with `X-Hookdeck-Signature`) | `hookdeck()` | -| 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 ` under the webhook's HTTP Headers in Supabase. - -Slack also ships as a chat channel in `@trigger.dev/slack`. - -For a complete project built on `resend()`, see the [Resend email agent example](https://github.com/triggerdotdev/examples/tree/main/resend-slack-email-agent). It drafts replies to a Resend inbox and waits for your approval in Slack before sending them. - -### Hookdeck - -`hookdeck()` verifies requests that a [Hookdeck](https://hookdeck.com) connection forwards to the endpoint. Hookdeck forwards the original provider's body unchanged, so pass that provider's event type: - -```ts /trigger/stripe-via-hookdeck.ts -import type Stripe from "stripe"; -import { webhook, webhooks } from "@trigger.dev/sdk"; - -export const stripeViaHookdeck = webhooks.endpoint.define({ - id: "stripe-via-hookdeck", - source: webhooks.hookdeck(), -}); - -export const paymentSucceeded = webhook({ - id: "payment-succeeded", - endpoint: stripeViaHookdeck, - filter: "event.type == 'payment_intent.succeeded'", - onEvent: async ({ event }) => { - console.log(event.id); - }, -}); -``` - -Use the endpoint URL as the connection's HTTP destination, keep the destination's authentication on Hookdeck Signature (the default for new destinations), and store the Hookdeck project's signing secret from **Settings > Secrets** as the endpoint's signing secret. - -- **Secret rotation:** when you roll the signing secret in Hookdeck with an expiry, Hookdeck also signs each request with the previous secret in `X-Hookdeck-Signature-2`, so deliveries keep verifying until you store the new secret. -- **Deduplication:** retries dedupe on `X-Hookdeck-Eventid`, which is the same on every attempt of a Hookdeck event. -- **Custom header prefix:** if you changed the header prefix in the Hookdeck project's settings, pass it with `webhooks.hookdeck({ headerPrefix: "x-acme" })`. The prefix renames the event id header; the signature headers keep the `X-Hookdeck-` name. - ## Endpoint validation Some sources also define a response for the provider's endpoint-validation request. These requests don't create deliveries or task runs. @@ -147,66 +96,6 @@ Slack's `url_verification` challenge is handled the same way by `@trigger.dev/sl `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: @@ -233,20 +122,8 @@ For `webhooks.custom()`, pass your own event type as `T`. The endpoint's even a TypeScript type. Validate `event` inside `onEvent` if your handler needs runtime schema checks. -## Verification schemes +## How verification works 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 (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. | - - - Query parameters can appear in access logs, proxies, and traces. Prefer a header-based scheme when - the provider supports one. - +To verify a provider without a built-in source, choose a scheme in a [custom source](/webhooks/custom-providers#verification-schemes). From 91812b8f1d8a481e0c7ce42f83e5693fb68ed84c Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:19:30 +0000 Subject: [PATCH 02/37] docs(webhooks): split how it works and pricing out of the overview Move the How it works and Pricing and limits sections to their own pages, drop the Connect it section, and cut the overview's card grid to three. --- docs/docs.json | 4 ++- docs/webhooks/how-it-works.mdx | 24 +++++++++++++ docs/webhooks/overview.mdx | 54 +++------------------------- docs/webhooks/pricing-and-limits.mdx | 13 +++++++ 4 files changed, 45 insertions(+), 50 deletions(-) create mode 100644 docs/webhooks/how-it-works.mdx create mode 100644 docs/webhooks/pricing-and-limits.mdx diff --git a/docs/docs.json b/docs/docs.json index 69c972550b3..72d417d1f3a 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -172,6 +172,7 @@ "pages": [ "webhooks/overview", "webhooks/quick-start", + "webhooks/how-it-works", "webhooks/sources", "webhooks/connect", { @@ -235,7 +236,8 @@ "webhooks/slack", "webhooks/linear", "webhooks/human-in-the-loop", - "webhooks/own-handler" + "webhooks/own-handler", + "webhooks/pricing-and-limits" ] }, { diff --git a/docs/webhooks/how-it-works.mdx b/docs/webhooks/how-it-works.mdx new file mode 100644 index 00000000000..a44d33177ab --- /dev/null +++ b/docs/webhooks/how-it-works.mdx @@ -0,0 +1,24 @@ +--- +title: "How webhooks work" +sidebarTitle: "How it works" +description: "What happens to a webhook request on Trigger.dev: verification, deduplication, recording the delivery, and routing it to subscribers." +--- + +**Every request is verified and deduplicated before it is recorded, then each subscriber's filter decides whether it runs.** + +```mermaid +flowchart LR + P[Provider] --> V[Verify] + V --> D[Deduplicate] + D --> R[Record delivery] + R --> F{Subscriber filters} + F --> T[Task runs] + F --> A[Agent sessions] + F --> W[Waiting runs resume] +``` + +The CLI finds your endpoints and subscribers during `trigger dev` and deployment, and each environment gets one endpoint per declared id. The endpoint holds the URL and the credential used to verify requests. + +A request must pass verification before anything else happens. Provider handshakes are answered directly and create no delivery. A verified request is checked for duplicates, recorded, and then routed: each subscriber's filter is checked, matching subscribers run, and waiting runs whose match fits the event are resumed. The delivery records a result per subscriber. + +See [Deliveries and endpoints](/webhooks/deliveries) for delivery statuses and replays, and [Filters](/webhooks/filters) for how subscribers choose events. diff --git a/docs/webhooks/overview.mdx b/docs/webhooks/overview.mdx index f4aeaae105c..f59cb894949 100644 --- a/docs/webhooks/overview.mdx +++ b/docs/webhooks/overview.mdx @@ -86,58 +86,14 @@ The limit covers every delivery the task handles. To process each customer's eve `webhooks.endpoint.define` also takes a `description` and `metadata`. The metadata is passed to every subscriber as `endpoint.metadata`. The endpoint `id` can't start with `wh_`, which is reserved for the ids Trigger.dev generates. -## How it works - -The CLI finds your endpoints and subscribers during `trigger dev` and deployment, and each environment gets one endpoint per declared id. The endpoint holds the URL and the credential used to verify requests. - -A request must pass verification before anything else happens. Provider handshakes are answered directly and create no delivery. A verified request is checked for duplicates, recorded, and then routed: each subscriber's filter is checked, matching subscribers run, and waiting runs whose match fits the event are resumed. The delivery records a result per subscriber. - -## Pricing and limits - -Webhooks have no separate charge on Trigger.dev Cloud. Receiving, verifying, filtering and recording deliveries is included in every plan. The runs a delivery starts or resumes are billed like any other run: a per-run invocation cost plus compute time. See [pricing](https://trigger.dev/pricing). - -A delivery that no subscriber's filter matches starts no run for any subscriber, so it costs nothing. A run already waiting for that webhook still resumes. A run [waiting](/webhooks/waiters) for a webhook is suspended, so it uses no compute until the webhook arrives. - -Each plan sets limits on the ingest rate, waiting runs, processing concurrency and how long deliveries are kept. See [Limits](/limits#webhook-ingest-rate-limits). - -Webhooks are open source, so they also work self-hosted. See [Self-hosting webhooks](/self-hosting/env/webapp#webhooks) to turn them on. - -## Connect it - -Every endpoint can produce a setup prompt for an AI coding agent. It holds the URL, the events your subscribers filter on, and the steps for registering the endpoint and its signing secret with the provider. Copy it from the endpoints list or the endpoint's page, or read it with the MCP server's `get_webhook_endpoint_details` tool. See [Connect a provider](/webhooks/connect). - - + - Install the SDK, declare an endpoint, and receive your first event. - - - Register the URL and signing secret, then send a test event. + Declare an endpoint and receive your first event. - Set up each built-in provider source. - - - Verify a provider that has no built-in source. - - - How sources verify requests and type the event. - - - Choose which events reach each subscriber. - - - Pause a run until a matching webhook arrives. - - - Inspect received events and where each one went. - - - Route deliveries to a durable per-key agent session. - - - Turn a webhook into a chat frontend for an agent. + Set up Stripe, GitHub, Firecrawl and 40+ other providers. - - Approvals and interactive controls over a channel. + + What happens to a request, from verification to runs. diff --git a/docs/webhooks/pricing-and-limits.mdx b/docs/webhooks/pricing-and-limits.mdx new file mode 100644 index 00000000000..e49cb856e9f --- /dev/null +++ b/docs/webhooks/pricing-and-limits.mdx @@ -0,0 +1,13 @@ +--- +title: "Webhooks pricing and limits" +sidebarTitle: "Pricing & limits" +description: "What webhooks cost on Trigger.dev Cloud, which plan limits apply, and how to run them self-hosted." +--- + +Webhooks have no separate charge on Trigger.dev Cloud. Receiving, verifying, filtering and recording deliveries is included in every plan. The runs a delivery starts or resumes are billed like any other run: a per-run invocation cost plus compute time. See [pricing](https://trigger.dev/pricing). + +A delivery that no subscriber's filter matches starts no run for any subscriber, so it costs nothing. A run already waiting for that webhook still resumes. A run [waiting](/webhooks/waiters) for a webhook is suspended, so it uses no compute until the webhook arrives. + +Each plan sets limits on the ingest rate, waiting runs, processing concurrency and how long deliveries are kept. See [Limits](/limits#webhook-ingest-rate-limits). + +Webhooks are open source, so they also work self-hosted. See [Self-hosting webhooks](/self-hosting/env/webapp#webhooks) to turn them on. From 5d7a25efc2dc57ba92e8887de64420b8c7a36f76 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:22:41 +0000 Subject: [PATCH 03/37] docs(webhooks): rename Sources & verification to Verification Say provider for the external service and source only for the endpoint's source field. Redirect /webhooks/sources to /webhooks/verification. --- docs/docs.json | 6 +++++- docs/guides/example-projects/resend-email-agent.mdx | 4 ++-- docs/webhooks/connect.mdx | 2 +- docs/webhooks/custom-providers.mdx | 2 +- docs/webhooks/deliveries.mdx | 2 +- docs/webhooks/filters.mdx | 2 +- docs/webhooks/overview.mdx | 6 +++--- docs/webhooks/providers.mdx | 4 ++-- docs/webhooks/{sources.mdx => verification.mdx} | 10 +++++----- 9 files changed, 21 insertions(+), 17 deletions(-) rename docs/webhooks/{sources.mdx => verification.mdx} (88%) diff --git a/docs/docs.json b/docs/docs.json index 72d417d1f3a..df5cb272f3c 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -173,7 +173,7 @@ "webhooks/overview", "webhooks/quick-start", "webhooks/how-it-works", - "webhooks/sources", + "webhooks/verification", "webhooks/connect", { "group": "Providers", @@ -856,6 +856,10 @@ ] }, "redirects": [ + { + "source": "/webhooks/sources", + "destination": "/webhooks/verification" + }, { "source": "/webhooks/public-beta", "destination": "/webhooks/overview" diff --git a/docs/guides/example-projects/resend-email-agent.mdx b/docs/guides/example-projects/resend-email-agent.mdx index 333966d9752..a0c38193975 100644 --- a/docs/guides/example-projects/resend-email-agent.mdx +++ b/docs/guides/example-projects/resend-email-agent.mdx @@ -157,8 +157,8 @@ An endpoint without its secret shows "Needs secret" on the Webhooks page. Pause a run until an external event completes a token. - - Every built-in source, including `resend()`, and how each is verified. + + Register the endpoint in Resend and set its signing secret. The Slack source and channel in `@trigger.dev/slack`. diff --git a/docs/webhooks/connect.mdx b/docs/webhooks/connect.mdx index ad1b315e494..c534b0c93ec 100644 --- a/docs/webhooks/connect.mdx +++ b/docs/webhooks/connect.mdx @@ -80,7 +80,7 @@ If no delivery appears, check that the provider uses the copied URL and that bot `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. -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. +The verify token answers the URL check. The signing secret verifies event deliveries. See [Verification](/webhooks/verification#endpoint-validation) for the response behavior. ## Rotate a credential diff --git a/docs/webhooks/custom-providers.mdx b/docs/webhooks/custom-providers.mdx index a5adb2e0ab3..eae6eefde05 100644 --- a/docs/webhooks/custom-providers.mdx +++ b/docs/webhooks/custom-providers.mdx @@ -1,7 +1,7 @@ --- title: "Custom webhook providers" sidebarTitle: "Custom providers" -description: "Verify webhooks from a provider that has no built-in source by passing your own HMAC, shared-secret, URL-secret or public-key configuration to webhooks.custom()." +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()." --- **`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 source. diff --git a/docs/webhooks/deliveries.mdx b/docs/webhooks/deliveries.mdx index 9d57f50880b..978a9e3001e 100644 --- a/docs/webhooks/deliveries.mdx +++ b/docs/webhooks/deliveries.mdx @@ -92,7 +92,7 @@ When the source maps a provider event ID, that ID becomes the key, so the provid | A header | GitHub (`X-GitHub-Delivery`), Svix and Autumn (`svix-id`), Standard Webhooks, Loops and Granola (`webhook-id`), Linear (`Linear-Delivery`), PagerDuty (`X-Webhook-Id`), Jira (`X-Atlassian-Webhook-Identifier`), Zendesk (`X-Zendesk-Webhook-Invocation-Id`), Attio (`Idempotency-Key`), Shopify (`X-Shopify-Webhook-Id`), Hookdeck (`X-Hookdeck-Eventid`, or `-eventid` with a custom header prefix) | | A body field | Stripe, Notion, Vercel, Intercom, WorkOS, Metronome, Mux, Langfuse and Plain (`id`), Square, Slack and Typeform (`event_id`), Firecrawl (`webhookId`) | -The other named sources (Zoom, Calendly, Sentry, DocuSign, ElevenLabs, Vapi, Retell, Tailscale, Infisical, PlanetScale, Supabase, Discord) use the fallback below. +The other built-in providers (Zoom, Calendly, Sentry, DocuSign, ElevenLabs, Vapi, Retell, Tailscale, Infisical, PlanetScale, Supabase, Discord) use the fallback below. If the source doesn't map an event ID, the key is derived from the raw body, timestamp, and signature. A retry with a different timestamp or signature can therefore produce a different key. For a [custom source](/webhooks/custom-providers), set `idempotencyField` to a stable event identifier when the provider supplies one. diff --git a/docs/webhooks/filters.mdx b/docs/webhooks/filters.mdx index 0c7495ee2da..504f317db45 100644 --- a/docs/webhooks/filters.mdx +++ b/docs/webhooks/filters.mdx @@ -27,7 +27,7 @@ export const largePayments = webhook({ The same `filter` works on a [`chat.event`](/webhooks/session-routing#filtering), a channel connector, and a [waiter](/webhooks/waiters), where it is checked after the waiter's `match`. -The filter is checked against the [endpoint's event type](/webhooks/sources#typing-the-event). Concrete types catch missing fields and incompatible literals. Fields typed as `unknown`, including values in Stripe's default `data.object`, allow arbitrary non-empty field paths. Operator literals and path structure are still checked. A filter built at runtime (typed as `string` rather than a string literal) skips the compile-time check, and is validated when the endpoint is deployed. +The filter is checked against the [endpoint's event type](/webhooks/verification#typing-the-event). Concrete types catch missing fields and incompatible literals. Fields typed as `unknown`, including values in Stripe's default `data.object`, allow arbitrary non-empty field paths. Operator literals and path structure are still checked. A filter built at runtime (typed as `string` rather than a string literal) skips the compile-time check, and is validated when the endpoint is deployed. ## Narrow a union event diff --git a/docs/webhooks/overview.mdx b/docs/webhooks/overview.mdx index f59cb894949..425bb9bfde5 100644 --- a/docs/webhooks/overview.mdx +++ b/docs/webhooks/overview.mdx @@ -4,7 +4,7 @@ description: "Receive provider webhooks on hosted, verified endpoints and route sidebarTitle: "Overview" --- -**A webhook endpoint is one hosted URL that you register with a provider.** Trigger.dev verifies every request against the endpoint's [source](/webhooks/sources), records it as a [delivery](/webhooks/deliveries), and hands the event to everything subscribed to the endpoint. +**A webhook endpoint is one hosted URL that you register with a provider.** Trigger.dev [verifies](/webhooks/verification) every request from the provider, records it as a [delivery](/webhooks/deliveries), and hands the event to everything subscribed to the endpoint. Webhooks are in public beta for every organization, in `@trigger.dev/sdk` 4.8.1 and later. The API @@ -13,7 +13,7 @@ sidebarTitle: "Overview" [eric@trigger.dev](mailto:eric@trigger.dev) with the delivery id (`whd_...`) or run id. -[Built-in sources](/webhooks/providers) cover Stripe, GitHub, Firecrawl, Linear and more than 40 other providers. To set one up from scratch, follow the [quick start](/webhooks/quick-start). +[Built-in providers](/webhooks/providers) include Stripe, GitHub, Firecrawl, Linear and more than 40 others. To set one up from scratch, follow the [quick start](/webhooks/quick-start). Declare the endpoint once, then subscribe to it: @@ -63,7 +63,7 @@ Each subscriber has its own [filter](/webhooks/filters), so one delivery can rea | Argument | Value | | --- | --- | -| `event` | The verified request body, parsed as JSON. Its TypeScript type comes from the [source](/webhooks/sources#typing-the-event). | +| `event` | The verified request body, parsed as JSON. Its TypeScript type comes from the [source](/webhooks/verification#typing-the-event). | | `headers` | Request headers as a Web `Headers` object, with case-insensitive `get()` and `has()` methods. Credentials such as signatures are removed. | | `endpoint` | The endpoint the delivery arrived on: `id`, `declaredId`, `tenantId`, `externalRef`, and the `metadata` you declared. | | `ctx` | The same [run context](/context) that regular tasks receive. | diff --git a/docs/webhooks/providers.mdx b/docs/webhooks/providers.mdx index b6a1a8cd622..028e74b6186 100644 --- a/docs/webhooks/providers.mdx +++ b/docs/webhooks/providers.mdx @@ -4,7 +4,7 @@ sidebarTitle: "All providers" description: "Every built-in webhook source, with its SDK function, the credential it verifies with, and a setup page for each provider." --- -**Each built-in source verifies one provider's signature scheme, so you declare the endpoint with one function call and set one credential.** Every provider below has a page with the source, where to register the URL, and how to set the credential. +**Each built-in provider has a source function that verifies its signature scheme, so you declare the endpoint with one function call and set one credential.** Every provider below has a page with the source, where to register the URL, and how to set the credential. | Provider | Source | Credential | | --- | --- | --- | @@ -55,4 +55,4 @@ description: "Every built-in webhook source, with its SDK function, the credenti | [Zendesk](/webhooks/providers/zendesk) | `webhooks.zendesk()` | You generate it, or the provider issues it | | [Zoom](/webhooks/providers/zoom) | `webhooks.zoom()` | Issued by the provider | -For a provider that isn't listed, define a [custom source](/webhooks/custom-providers). For providers that sign with Svix or Standard Webhooks, `webhooks.svix()` and `webhooks.standardWebhooks()` also work; see [Sources and verification](/webhooks/sources#svix-and-standard-webhooks). +For a provider that isn't listed, define a [custom source](/webhooks/custom-providers). For providers that sign with Svix or Standard Webhooks, `webhooks.svix()` and `webhooks.standardWebhooks()` also work; see [Sources and verification](/webhooks/verification#svix-and-standard-webhooks). diff --git a/docs/webhooks/sources.mdx b/docs/webhooks/verification.mdx similarity index 88% rename from docs/webhooks/sources.mdx rename to docs/webhooks/verification.mdx index 64cc40cb22c..aa93c128ec8 100644 --- a/docs/webhooks/sources.mdx +++ b/docs/webhooks/verification.mdx @@ -1,10 +1,10 @@ --- -title: "Sources and verification" -description: "Choose an endpoint's source, configure verification, and type the event its subscribers receive." -sidebarTitle: "Sources & verification" +title: "Webhook verification" +description: "How an endpoint verifies each provider's requests, answers provider handshakes, and types the event its subscribers receive." +sidebarTitle: "Verification" --- -An endpoint's `source` defines how Trigger.dev verifies requests and types the event every subscriber receives. Choose a [built-in provider source](/webhooks/providers), such as `webhooks.stripe()` or `webhooks.firecrawl()`, or supply a verification configuration with [`webhooks.custom()`](/webhooks/custom-providers). +**An endpoint's `source` tells Trigger.dev how to verify a provider's requests and what type the event has.** Use a [built-in provider](/webhooks/providers), such as `webhooks.stripe()` or `webhooks.firecrawl()`, or describe the provider's scheme with [`webhooks.custom()`](/webhooks/custom-providers). ## Presets @@ -126,4 +126,4 @@ For `webhooks.custom()`, pass your own event type as `T`. The endpoint's even 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). -To verify a provider without a built-in source, choose a scheme in a [custom source](/webhooks/custom-providers#verification-schemes). +To verify a provider that isn't built in, choose a scheme in a [custom source](/webhooks/custom-providers#verification-schemes). From 7121333632e191df407079a15c8a3f4da6822bf9 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:24:39 +0000 Subject: [PATCH 04/37] docs(webhooks): lead the own-handler page with the built-in recommendation --- docs/webhooks/own-handler.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/webhooks/own-handler.mdx b/docs/webhooks/own-handler.mdx index 9842c54a9bb..b32f0a247bc 100644 --- a/docs/webhooks/own-handler.mdx +++ b/docs/webhooks/own-handler.mdx @@ -1,10 +1,12 @@ --- title: "Use your own webhook handler" sidebarTitle: "Using your own handler" -description: "Receive a webhook in a route in your own app, verify it yourself, and trigger a task from it instead of using a hosted endpoint." +description: "Trigger.dev has built-in webhook endpoints, which we recommend for most projects. If you prefer to handle webhooks yourself, receive them in your own app and trigger runs from there." --- -**A webhook handler in your own app can trigger a task with `tasks.trigger()`, the same way any backend code does.** Use it when you need to handle the request yourself. For most providers, a hosted [webhook endpoint](/webhooks/overview) does the same job with less code. +**Trigger.dev has built-in webhook endpoints, and we recommend them for most projects.** They verify each provider's signature, drop duplicate retries, record every delivery, and route events to tasks, agents and waiting runs. See [Webhooks](/webhooks/overview). + +If you prefer to handle webhooks yourself, receive them in a route in your own app and trigger runs from there with `tasks.trigger()`, the same way any backend code does. ## When to use your own handler From 7e9785d9d386a89b8a4e89bee2e649671de54e68 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:26:11 +0000 Subject: [PATCH 05/37] docs(webhooks): split signing secrets out of Connect a provider Connect a provider now covers only registering the URL and credential and checking delivery. Rotation, CLI, MCP and REST secret management move to a Signing secrets page, and the WhatsApp verify token moves to its provider page. Verification moves below Providers in the sidebar. --- docs/docs.json | 3 +- docs/webhooks/connect.mdx | 71 ++---------------------- docs/webhooks/providers/whatsapp.mdx | 8 ++- docs/webhooks/signing-secrets.mdx | 80 ++++++++++++++++++++++++++++ docs/webhooks/verification.mdx | 2 +- 5 files changed, 94 insertions(+), 70 deletions(-) create mode 100644 docs/webhooks/signing-secrets.mdx diff --git a/docs/docs.json b/docs/docs.json index df5cb272f3c..dd2d84eb882 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -173,8 +173,8 @@ "webhooks/overview", "webhooks/quick-start", "webhooks/how-it-works", - "webhooks/verification", "webhooks/connect", + "webhooks/signing-secrets", { "group": "Providers", "pages": [ @@ -228,6 +228,7 @@ ] }, "webhooks/custom-providers", + "webhooks/verification", "webhooks/deliveries", "webhooks/filters", "webhooks/waiters", diff --git a/docs/webhooks/connect.mdx b/docs/webhooks/connect.mdx index c534b0c93ec..5c6d8b27150 100644 --- a/docs/webhooks/connect.mdx +++ b/docs/webhooks/connect.mdx @@ -1,6 +1,6 @@ --- title: "Connect a webhook provider" -description: "Register an endpoint's URL and signing secret with the provider, by hand or with an AI coding agent, then check that events arrive." +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." sidebarTitle: "Connect a provider" --- @@ -8,49 +8,6 @@ Connect a provider to an [endpoint](/webhooks/overview) by registering the endpo 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. -## Set it up with an AI agent - -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. - -The prompt tells the agent to use the Trigger.dev MCP server (`npx trigger.dev@latest install-mcp`), which has these tools: - -| Tool | What it does | -| --- | --- | -| `list_webhook_endpoints` | Lists the environment's endpoints, with their URL and whether a secret is set. | -| `get_webhook_endpoint_details` | Reads one endpoint: URL, subscribers and their filters, secret state, and the setup prompt. | -| `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`). | -| `set_webhook_secret` | Stores a secret the provider issued. Optionally keeps accepting the old secret (`previousSecretTtlSeconds`). | - -### Keep the secret out of the agent's context - -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: - -```bash -# Store a secret the provider issued, from an env file or a pipe -npx trigger.dev@latest webhooks set-secret stripe --env prod --from-env STRIPE_WEBHOOK_SECRET - -# Generate one and save it to .env.local for the agent to pass to the provider by name -npx trigger.dev@latest webhooks generate-secret github --env prod --to-env GITHUB_WEBHOOK_SECRET -``` - -Without the MCP server, the same operations are available on the REST API with the environment's secret key: - -| Request | What it does | -| --- | --- | -| [`GET /api/v1/webhooks/endpoints`](/management/webhooks/list-endpoints) | Lists the environment's endpoints, with their URL and whether a secret is set. | -| [`GET /api/v1/webhooks/endpoints/{endpointId}`](/management/webhooks/retrieve-endpoint) | Reads the endpoint, including `subscribers` and `setupPrompt`. | -| [`POST /api/v1/webhooks/endpoints/{endpointId}/rotate-secret`](/management/webhooks/generate-secret) | Generates a secret and returns it once. | -| [`PUT /api/v1/webhooks/endpoints/{endpointId}/secret`](/management/webhooks/set-secret) | Stores a secret, sent as `{ "secret": "..." }`. | - -`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`: - -```bash -curl -X PUT "https://api.trigger.dev/api/v1/webhooks/endpoints/stripe/secret" \ - -H "Authorization: Bearer $TRIGGER_SECRET_KEY" \ - -H "Content-Type: application/json" \ - -d '{"secret": "whsec_..."}' -``` - ## Set it up by hand @@ -76,28 +33,8 @@ Send a test event from your provider, or use the endpoint's **Test** tab. The ev If no delivery appears, check that the provider uses the copied URL and that both sides have the same signing secret or public key. -## Verify a WhatsApp endpoint URL - -`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. - -The verify token answers the URL check. The signing secret verifies event deliveries. See [Verification](/webhooks/verification#endpoint-validation) for the response behavior. - -## Rotate a credential - -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. - -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. - -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: +## Set it up with an AI agent -```bash -curl -X POST "https://api.trigger.dev/api/v1/webhooks/endpoints/github/rotate-secret" \ - -H "Authorization: Bearer $TRIGGER_SECRET_KEY" \ - -H "Content-Type: application/json" \ - -d '{"previousSecretTtlSeconds": 3600}' -``` +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. - - Trigger.dev stores credentials encrypted and doesn't display saved values. Copy a generated secret - before closing the dialog. - +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. diff --git a/docs/webhooks/providers/whatsapp.mdx b/docs/webhooks/providers/whatsapp.mdx index fde82c5de81..9ab52b209cb 100644 --- a/docs/webhooks/providers/whatsapp.mdx +++ b/docs/webhooks/providers/whatsapp.mdx @@ -33,7 +33,13 @@ export const whatsappEvents = webhook({ ## Set up WhatsApp 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. In the Meta app dashboard, set the WhatsApp webhook's callback URL to the webhook URL. Meta verifies the URL with a GET request that needs a verify token; see [Verify a WhatsApp endpoint URL](/webhooks/connect#verify-a-whatsapp-endpoint-url). +2. In the Meta app dashboard, set the WhatsApp webhook's callback URL to the webhook URL. Meta checks the URL with a GET request that needs a verify token; see [Verify the callback URL](#verify-the-callback-url). 3. Copy the app's **App Secret**, then choose **Set signing secret** on the Trigger.dev endpoint. Meta signs event deliveries with it. 4. Subscribe the webhook to the fields your subscribers need, such as `messages`. 5. Send a test event from WhatsApp, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. + +## Verify the callback URL + +`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. + +The verify token answers the URL check. The signing secret verifies event deliveries. See [Verification](/webhooks/verification#endpoint-validation) for the response behavior. diff --git a/docs/webhooks/signing-secrets.mdx b/docs/webhooks/signing-secrets.mdx new file mode 100644 index 00000000000..1344a78d0ae --- /dev/null +++ b/docs/webhooks/signing-secrets.mdx @@ -0,0 +1,80 @@ +--- +title: "Webhook signing secrets" +sidebarTitle: "Signing secrets" +description: "Set, generate and rotate the credential an endpoint verifies deliveries with, from the dashboard, the CLI, the MCP server or the REST API." +--- + +**Each endpoint verifies deliveries with one credential: a signing secret, or a public key for providers that sign with a key pair.** Every delivery is rejected until the credential is set. + +## Set the credential + +| Action | Use it when | +| --- | --- | +| **Set signing secret** | The provider issues the secret, as Stripe and Svix do. | +| **Generate secret** | The provider accepts a secret you choose, as GitHub does. Trigger.dev shows it once. | +| **Set public key** | The provider signs with a key pair, as Discord does. | + +Each [provider page](/webhooks/providers) says which one that provider needs. + +## Rotate a credential + +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. + +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. + +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: + +```bash +curl -X POST "https://api.trigger.dev/api/v1/webhooks/endpoints/github/rotate-secret" \ + -H "Authorization: Bearer $TRIGGER_SECRET_KEY" \ + -H "Content-Type: application/json" \ + -d '{"previousSecretTtlSeconds": 3600}' +``` + + + Trigger.dev stores credentials encrypted and doesn't display saved values. Copy a generated secret + before closing the dialog. + + +## Store secrets from the CLI + +The [CLI webhooks commands](/cli-webhooks-commands) store a secret without printing it. Use them with AI agents that can run shell commands: a secret passed to `set_webhook_secret`, or returned by `generate_webhook_secret`, becomes part of the agent's conversation, and the MCP tool descriptions point agents to the CLI instead. + +```bash +# Store a secret the provider issued, from an env file or a pipe +npx trigger.dev@latest webhooks set-secret stripe --env prod --from-env STRIPE_WEBHOOK_SECRET + +# Generate one and save it to .env.local for the agent to pass to the provider by name +npx trigger.dev@latest webhooks generate-secret github --env prod --to-env GITHUB_WEBHOOK_SECRET +``` + +## MCP tools + +The Trigger.dev MCP server (`npx trigger.dev@latest install-mcp`) has these webhook tools: + +| Tool | What it does | +| --- | --- | +| `list_webhook_endpoints` | Lists the environment's endpoints, with their URL and whether a secret is set. | +| `get_webhook_endpoint_details` | Reads one endpoint: URL, subscribers and their filters, secret state, and the setup prompt. | +| `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`). | +| `set_webhook_secret` | Stores a secret the provider issued. Optionally keeps accepting the old secret (`previousSecretTtlSeconds`). | + +## REST API + +The same operations are available on the REST API with the environment's secret key: + +| Request | What it does | +| --- | --- | +| [`GET /api/v1/webhooks/endpoints`](/management/webhooks/list-endpoints) | Lists the environment's endpoints, with their URL and whether a secret is set. | +| [`GET /api/v1/webhooks/endpoints/{endpointId}`](/management/webhooks/retrieve-endpoint) | Reads the endpoint, including `subscribers` and `setupPrompt`. | +| [`POST /api/v1/webhooks/endpoints/{endpointId}/rotate-secret`](/management/webhooks/generate-secret) | Generates a secret and returns it once. | +| [`PUT /api/v1/webhooks/endpoints/{endpointId}/secret`](/management/webhooks/set-secret) | Stores a secret, sent as `{ "secret": "..." }`. | + +`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`: + +```bash +curl -X PUT "https://api.trigger.dev/api/v1/webhooks/endpoints/stripe/secret" \ + -H "Authorization: Bearer $TRIGGER_SECRET_KEY" \ + -H "Content-Type: application/json" \ + -d '{"secret": "whsec_..."}' +``` diff --git a/docs/webhooks/verification.mdx b/docs/webhooks/verification.mdx index aa93c128ec8..02958898d88 100644 --- a/docs/webhooks/verification.mdx +++ b/docs/webhooks/verification.mdx @@ -94,7 +94,7 @@ Some sources also define a response for the provider's endpoint-validation reque 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. +`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/providers/whatsapp#verify-the-callback-url). Endpoints without GET verification return `405` to GET requests. ## Typing the event From 3c12c039a6787eaac9d2b5bbd5c89b03dcbeb6a9 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:28:05 +0000 Subject: [PATCH 06/37] docs(webhooks): say Slack and Linear are deep integrations, not raw event providers --- docs/webhooks/linear.mdx | 2 ++ docs/webhooks/slack.mdx | 2 ++ 2 files changed, 4 insertions(+) diff --git a/docs/webhooks/linear.mdx b/docs/webhooks/linear.mdx index 48694962103..003f9dc9c30 100644 --- a/docs/webhooks/linear.mdx +++ b/docs/webhooks/linear.mdx @@ -6,6 +6,8 @@ sidebarTitle: "Linear agents" Linear opens an **agent session** when someone @mentions your app in an issue or delegates (assigns) an issue to it. `linear()` from `@trigger.dev/linear` is a [channel](/webhooks/channels) connector for those sessions: each one becomes a durable Trigger.dev [session](/ai-chat/sessions), the user's prompt runs as a turn, and the agent's work shows up in Linear as thoughts, actions, a plan, an approval card when it needs a decision, and a response when it is done. +Linear and [Slack](/webhooks/slack) have deep integrations built on top of webhooks. Other [providers](/webhooks/providers) deliver raw events for your task to handle. The Linear connector also implements Linear's agent session UI, so you don't post thoughts, plans or approval cards yourself. To receive Linear events without an agent, see the [Linear provider page](/webhooks/providers/linear). + ```ts import { webhooks } from "@trigger.dev/sdk"; import { chat } from "@trigger.dev/sdk/ai"; diff --git a/docs/webhooks/slack.mdx b/docs/webhooks/slack.mdx index 1be48e5e2dd..1967d57c237 100644 --- a/docs/webhooks/slack.mdx +++ b/docs/webhooks/slack.mdx @@ -6,6 +6,8 @@ sidebarTitle: "Slack agents" **`slack()` from `@trigger.dev/slack` turns a `chat.agent` into a native Slack agent.** Each Slack agent session (a conversation with the agent, or a thread in a channel) becomes a durable Trigger.dev [session](/ai-chat/sessions). A message runs as a turn, the session shows the agent working, the reply streams into the thread as the model writes it, and Slack's stop button stops the turn. +Slack and [Linear](/webhooks/linear) have deep integrations built on top of webhooks. Other [providers](/webhooks/providers) deliver raw events for your task to handle. The Slack connector also implements Slack's agent features, so you don't build status updates, streaming replies or approvals yourself. To receive Slack events without an agent, see the [Slack provider page](/webhooks/providers/slack). + ```ts /trigger/support.ts import { webhooks } from "@trigger.dev/sdk"; import { chat } from "@trigger.dev/sdk/ai"; From 7482b5af34e84b4720e01137651649ed02773539 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:29:42 +0000 Subject: [PATCH 07/37] docs(webhooks): shorten the Slack and Linear integration note to one sentence --- docs/webhooks/linear.mdx | 2 +- docs/webhooks/slack.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/webhooks/linear.mdx b/docs/webhooks/linear.mdx index 003f9dc9c30..f14cab5cc6c 100644 --- a/docs/webhooks/linear.mdx +++ b/docs/webhooks/linear.mdx @@ -6,7 +6,7 @@ sidebarTitle: "Linear agents" Linear opens an **agent session** when someone @mentions your app in an issue or delegates (assigns) an issue to it. `linear()` from `@trigger.dev/linear` is a [channel](/webhooks/channels) connector for those sessions: each one becomes a durable Trigger.dev [session](/ai-chat/sessions), the user's prompt runs as a turn, and the agent's work shows up in Linear as thoughts, actions, a plan, an approval card when it needs a decision, and a response when it is done. -Linear and [Slack](/webhooks/slack) have deep integrations built on top of webhooks. Other [providers](/webhooks/providers) deliver raw events for your task to handle. The Linear connector also implements Linear's agent session UI, so you don't post thoughts, plans or approval cards yourself. To receive Linear events without an agent, see the [Linear provider page](/webhooks/providers/linear). +Unlike other [providers](/webhooks/providers), which deliver raw events, Linear is a deep integration: the connector handles Linear's agent session UI for you. ```ts import { webhooks } from "@trigger.dev/sdk"; diff --git a/docs/webhooks/slack.mdx b/docs/webhooks/slack.mdx index 1967d57c237..d9343161954 100644 --- a/docs/webhooks/slack.mdx +++ b/docs/webhooks/slack.mdx @@ -6,7 +6,7 @@ sidebarTitle: "Slack agents" **`slack()` from `@trigger.dev/slack` turns a `chat.agent` into a native Slack agent.** Each Slack agent session (a conversation with the agent, or a thread in a channel) becomes a durable Trigger.dev [session](/ai-chat/sessions). A message runs as a turn, the session shows the agent working, the reply streams into the thread as the model writes it, and Slack's stop button stops the turn. -Slack and [Linear](/webhooks/linear) have deep integrations built on top of webhooks. Other [providers](/webhooks/providers) deliver raw events for your task to handle. The Slack connector also implements Slack's agent features, so you don't build status updates, streaming replies or approvals yourself. To receive Slack events without an agent, see the [Slack provider page](/webhooks/providers/slack). +Unlike other [providers](/webhooks/providers), which deliver raw events, Slack is a deep integration: the connector handles Slack's agent features for you. ```ts /trigger/support.ts import { webhooks } from "@trigger.dev/sdk"; From 0cd44f5cf57933f72e076a766f694cb20a562928 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:30:21 +0000 Subject: [PATCH 08/37] docs(webhooks): reword the Slack and Linear integration note --- docs/webhooks/linear.mdx | 2 +- docs/webhooks/slack.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/webhooks/linear.mdx b/docs/webhooks/linear.mdx index f14cab5cc6c..239a99cf814 100644 --- a/docs/webhooks/linear.mdx +++ b/docs/webhooks/linear.mdx @@ -6,7 +6,7 @@ sidebarTitle: "Linear agents" Linear opens an **agent session** when someone @mentions your app in an issue or delegates (assigns) an issue to it. `linear()` from `@trigger.dev/linear` is a [channel](/webhooks/channels) connector for those sessions: each one becomes a durable Trigger.dev [session](/ai-chat/sessions), the user's prompt runs as a turn, and the agent's work shows up in Linear as thoughts, actions, a plan, an approval card when it needs a decision, and a response when it is done. -Unlike other [providers](/webhooks/providers), which deliver raw events, Linear is a deep integration: the connector handles Linear's agent session UI for you. +Linear is one of our deep integrations: as well as delivering [webhook events](/webhooks/providers/linear), the connector handles Linear's agent session UI for you. ```ts import { webhooks } from "@trigger.dev/sdk"; diff --git a/docs/webhooks/slack.mdx b/docs/webhooks/slack.mdx index d9343161954..6ff93f64cc8 100644 --- a/docs/webhooks/slack.mdx +++ b/docs/webhooks/slack.mdx @@ -6,7 +6,7 @@ sidebarTitle: "Slack agents" **`slack()` from `@trigger.dev/slack` turns a `chat.agent` into a native Slack agent.** Each Slack agent session (a conversation with the agent, or a thread in a channel) becomes a durable Trigger.dev [session](/ai-chat/sessions). A message runs as a turn, the session shows the agent working, the reply streams into the thread as the model writes it, and Slack's stop button stops the turn. -Unlike other [providers](/webhooks/providers), which deliver raw events, Slack is a deep integration: the connector handles Slack's agent features for you. +Slack is one of our deep integrations: as well as delivering [webhook events](/webhooks/providers/slack), the connector handles Slack's agent features for you. ```ts /trigger/support.ts import { webhooks } from "@trigger.dev/sdk"; From 56c5d4bcd67f353c3ec40b6e3eefdeab8aa872f0 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:33:36 +0000 Subject: [PATCH 09/37] docs(webhooks): rewrite How it works around store-then-answer Explain the request lifecycle (verify, dedupe, store, answer, route), endpoints declared in code, shared endpoints with many subscribers, two-layer deduplication, and recorded deliveries. --- docs/webhooks/how-it-works.mdx | 64 +++++++++++++++++++++++++++------- 1 file changed, 51 insertions(+), 13 deletions(-) diff --git a/docs/webhooks/how-it-works.mdx b/docs/webhooks/how-it-works.mdx index a44d33177ab..1127d8ee785 100644 --- a/docs/webhooks/how-it-works.mdx +++ b/docs/webhooks/how-it-works.mdx @@ -1,24 +1,62 @@ --- title: "How webhooks work" sidebarTitle: "How it works" -description: "What happens to a webhook request on Trigger.dev: verification, deduplication, recording the delivery, and routing it to subscribers." +description: "Trigger.dev verifies, deduplicates and stores every webhook before answering the provider, then routes it to tasks, waiting runs and agents." --- -**Every request is verified and deduplicated before it is recorded, then each subscriber's filter decides whether it runs.** +**Trigger.dev stores every webhook before it answers the provider, then routes it to the tasks, waiting runs and agents subscribed to the endpoint.** + +A webhook is an HTTP request a provider such as Stripe or GitHub sends to your URL when something happens. Providers expect a fast `2xx` response and retry until they get one, so the same event can arrive more than once. A handler that does slow work before answering, or answers before saving the event, can time out, run twice or lose the event. + +## What happens to a request ```mermaid -flowchart LR - P[Provider] --> V[Verify] - V --> D[Deduplicate] - D --> R[Record delivery] - R --> F{Subscriber filters} - F --> T[Task runs] - F --> A[Agent sessions] - F --> W[Waiting runs resume] +sequenceDiagram + participant P as Provider + participant T as Trigger.dev + participant S as Subscribers + P->>T: POST to the endpoint URL + Note over T: Verify, deduplicate, store + T-->>P: 200 OK + T->>S: Start runs, resume waiting runs, message agents ``` -The CLI finds your endpoints and subscribers during `trigger dev` and deployment, and each environment gets one endpoint per declared id. The endpoint holds the URL and the credential used to verify requests. +1. **Verify.** The endpoint checks the provider's signature or secret with the endpoint's [credential](/webhooks/signing-secrets). A request that fails is rejected and never reaches a subscriber. Provider handshakes, such as Slack's URL check, are answered here and create no delivery. +2. **Deduplicate.** A retry of an event that already arrived is answered as a duplicate. Most [built-in providers](/webhooks/providers) dedupe on the provider's event ID. +3. **Store, then answer.** The delivery is durably stored before the provider gets its `200`. Once the provider has its answer it stops retrying, and Trigger.dev is responsible for the event from then on. +4. **Route.** Each subscriber's [filter](/webhooks/filters) is checked. Matching tasks start a run, matching [waiters](/webhooks/waiters) resume their paused runs, and agent sessions receive the event as a message. + +Each endpoint and environment has a rate limit. Over it, the endpoint answers `429` with `Retry-After`, so the provider sends the event again later instead of dropping it. See [Limits](/limits#webhook-ingest-rate-limits). + +## Endpoints are declared in code + +You declare an endpoint next to your tasks with `webhooks.endpoint.define()`. When you run `trigger dev` or deploy, the CLI sends the endpoints it finds to Trigger.dev, and the environment is synced to match: new endpoints are created, and removed ones are deactivated but keep their URL and secret, so adding one back restores it. + +Each environment gets its own URL for each endpoint. Your dev environment has its own URL too, so you don't need a tunnel for local development. A delivery that arrives while `trigger dev` isn't running waits for it like any other dev run. + +## One endpoint, many subscribers + +A provider account usually needs one URL, so every subscriber shares the endpoint. One delivery can reach up to 25 subscribers: + +| Subscriber | What a matching delivery does | +| --- | --- | +| Task, declared with `webhook()` | Starts a run with the event as its payload. | +| [Waiter](/webhooks/waiters) | Resumes a run that paused until this event arrived. | +| Agent session, via [session routing](/webhooks/session-routing) or a [channel](/webhooks/channels) | Delivers the event to the right conversation, so the agent acts with its full history. | + +A delivery that no filter matches is recorded as `FILTERED` and starts no run, so it costs nothing. See [Pricing and limits](/webhooks/pricing-and-limits). + +## Retries and duplicates + +Duplicates are caught in two places: + +- **When the webhook arrives.** A retry with the same event ID is answered as a duplicate and isn't stored again. +- **When the run starts.** Each delivery triggers its task with an [idempotency key](/idempotency) built from the endpoint and the event, kept for the provider's retry window. A retry that gets past the first check finds the existing run instead of starting a second one. + +A waiter completes once, and an agent session skips an event it has already received. A resend after the retry window, such as resending an event from the provider's dashboard a week later, starts a new run, so keep side effects in your handler idempotent. + +If a provider sends no event ID, the key comes from the body, timestamp and signature. See [Deduplication](/webhooks/deliveries#deduplication). -A request must pass verification before anything else happens. Provider handshakes are answered directly and create no delivery. A verified request is checked for duplicates, recorded, and then routed: each subscriber's filter is checked, matching subscribers run, and waiting runs whose match fits the event are resumed. The delivery records a result per subscriber. +## Every delivery is recorded -See [Deliveries and endpoints](/webhooks/deliveries) for delivery statuses and replays, and [Filters](/webhooks/filters) for how subscribers choose events. +Each delivery keeps its headers, body and the result for every subscriber, with links to the runs it started. A filtered delivery shows which clause failed and with what value. You can replay a delivery from the dashboard, the REST API or the MCP server. See [Deliveries and endpoints](/webhooks/deliveries). From 3cccc2cae538ec5c803d507ae36818a9a81a3abd Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:35:12 +0000 Subject: [PATCH 10/37] docs(webhooks): link How it works to the How we built webhooks post --- docs/webhooks/how-it-works.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/webhooks/how-it-works.mdx b/docs/webhooks/how-it-works.mdx index 1127d8ee785..edacd282e07 100644 --- a/docs/webhooks/how-it-works.mdx +++ b/docs/webhooks/how-it-works.mdx @@ -60,3 +60,5 @@ If a provider sends no event ID, the key comes from the body, timestamp and sign ## Every delivery is recorded Each delivery keeps its headers, body and the result for every subscriber, with links to the runs it started. A filtered delivery shows which clause failed and with what value. You can replay a delivery from the dashboard, the REST API or the MCP server. See [Deliveries and endpoints](/webhooks/deliveries). + +For the design choices and infrastructure behind this, read [How we built webhooks](https://trigger.dev/blog/how-we-built-webhooks). From 91ab97ab5ec69522a97044fd1dc71af017e56d19 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:36:14 +0000 Subject: [PATCH 11/37] docs(webhooks): say where to find the endpoint in the quick start --- docs/webhooks/quick-start.mdx | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/webhooks/quick-start.mdx b/docs/webhooks/quick-start.mdx index 6031110ddb7..591f256ef8e 100644 --- a/docs/webhooks/quick-start.mdx +++ b/docs/webhooks/quick-start.mdx @@ -95,19 +95,21 @@ bunx trigger.dev@latest dev -The CLI registers the endpoint, and it appears on the dev environment's **Webhooks** page with the **Signing secret** column set to **Needs secret**. +The CLI registers the `github` endpoint you declared in your **Development** environment. -Open the `github` endpoint and choose **Generate secret**. The column changes to **Ready**. Every delivery is rejected until an endpoint has its secret. +In the [Trigger.dev dashboard](https://cloud.trigger.dev), open your project, make sure the **Development** environment is selected, and choose **Webhooks** in the side menu. The `github` endpoint is listed with its **Signing secret** column set to **Needs secret**. Every delivery is rejected until an endpoint has its secret. + +Open the `github` endpoint and choose **Generate secret**. The secret is shown once: copy it if you'll connect GitHub later. Back on the **Webhooks** page, the column now says **Ready**. -Open the endpoint's **Test** tab and send the sample event. The delivery appears on the **Deliveries** tab with the `github-events` subscriber listed. Follow the link to its run to see the logged event. +On the `github` endpoint's page, open the **Test** tab, pick a sample event and choose **Send event**. The delivery appears on the **Deliveries** tab. Open it to see that it reached the `github-events` subscriber, then follow the link to the run to see the logged event. From a5f8bb16ba2046574da0ebad3f6107a27dae2b66 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:36:52 +0000 Subject: [PATCH 12/37] docs(webhooks): mention building AI agents on webhook events in the overview --- docs/webhooks/overview.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/webhooks/overview.mdx b/docs/webhooks/overview.mdx index 425bb9bfde5..21a11d37f57 100644 --- a/docs/webhooks/overview.mdx +++ b/docs/webhooks/overview.mdx @@ -6,6 +6,8 @@ sidebarTitle: "Overview" **A webhook endpoint is one hosted URL that you register with a provider.** Trigger.dev [verifies](/webhooks/verification) every request from the provider, records it as a [delivery](/webhooks/deliveries), and hands the event to everything subscribed to the endpoint. +Use webhooks to build AI agents that run on events from the services you already use: a Stripe payment, a GitHub pull request or a Slack message can start an agent, resume one that's waiting, or land in an agent's conversation. + Webhooks are in public beta for every organization, in `@trigger.dev/sdk` 4.8.1 and later. The API may change before general availability; we announce changes in the From 1ccca99caf2c4cd78cb7b2e7cd870f4c165b9615 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:41:13 +0000 Subject: [PATCH 13/37] docs(webhooks): point to custom providers and own handlers from the overview --- docs/webhooks/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/webhooks/overview.mdx b/docs/webhooks/overview.mdx index 21a11d37f57..460635f2cbd 100644 --- a/docs/webhooks/overview.mdx +++ b/docs/webhooks/overview.mdx @@ -15,7 +15,7 @@ Use webhooks to build AI agents that run on events from the services you already [eric@trigger.dev](mailto:eric@trigger.dev) with the delivery id (`whd_...`) or run id. -[Built-in providers](/webhooks/providers) include Stripe, GitHub, Firecrawl, Linear and more than 40 others. To set one up from scratch, follow the [quick start](/webhooks/quick-start). +[Built-in providers](/webhooks/providers) include Stripe, GitHub, Firecrawl, Linear and more than 40 others. For any other provider, define a [custom provider](/webhooks/custom-providers). If you prefer to handle webhooks in your own app, you can [trigger tasks from your own handler](/webhooks/own-handler). To set one up from scratch, follow the [quick start](/webhooks/quick-start). Declare the endpoint once, then subscribe to it: From 37344180a0ea3b0aa52eba35a6a0e93004dfff94 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:41:54 +0000 Subject: [PATCH 14/37] docs(webhooks): shorten the AI agents line in the overview --- docs/webhooks/overview.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/webhooks/overview.mdx b/docs/webhooks/overview.mdx index 460635f2cbd..e539750fe9d 100644 --- a/docs/webhooks/overview.mdx +++ b/docs/webhooks/overview.mdx @@ -6,7 +6,7 @@ sidebarTitle: "Overview" **A webhook endpoint is one hosted URL that you register with a provider.** Trigger.dev [verifies](/webhooks/verification) every request from the provider, records it as a [delivery](/webhooks/deliveries), and hands the event to everything subscribed to the endpoint. -Use webhooks to build AI agents that run on events from the services you already use: a Stripe payment, a GitHub pull request or a Slack message can start an agent, resume one that's waiting, or land in an agent's conversation. +Webhooks can start, resume or message your AI agents. Webhooks are in public beta for every organization, in `@trigger.dev/sdk` 4.8.1 and later. The API From 89fc4a3d7fb0d64cf584c7045047f6725d36b23e Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:43:52 +0000 Subject: [PATCH 15/37] docs(webhooks): move handler details from the overview to a Webhook tasks page --- docs/docs.json | 1 + docs/webhooks/overview.mdx | 31 +--------------------- docs/webhooks/webhook-tasks.mdx | 46 +++++++++++++++++++++++++++++++++ 3 files changed, 48 insertions(+), 30 deletions(-) create mode 100644 docs/webhooks/webhook-tasks.mdx diff --git a/docs/docs.json b/docs/docs.json index dd2d84eb882..8fd19a6848b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -231,6 +231,7 @@ "webhooks/verification", "webhooks/deliveries", "webhooks/filters", + "webhooks/webhook-tasks", "webhooks/waiters", "webhooks/session-routing", "webhooks/channels", diff --git a/docs/webhooks/overview.mdx b/docs/webhooks/overview.mdx index e539750fe9d..6bdeee30501 100644 --- a/docs/webhooks/overview.mdx +++ b/docs/webhooks/overview.mdx @@ -57,36 +57,7 @@ Stripe gets one URL. A checkout event runs `fulfill-order`, a refund runs `recor | Chat frontend | a [channel connector](/webhooks/channels) such as `chat.channels.custom({ endpoint })` | Runs a turn on the conversation's session and posts the reply back. | | Waiting run | [`webhooks.waiter.create(endpoint, { match })`](/webhooks/waiters) | Resumes a run that is waiting for this event. | -Each subscriber has its own [filter](/webhooks/filters), so one delivery can reach several subscribers and skip the rest. An endpoint can have up to 25 subscribers. An endpoint with no subscribers still gets a URL, so you can register it with the provider before writing the handlers. - -## The handler - -`onEvent` receives: - -| Argument | Value | -| --- | --- | -| `event` | The verified request body, parsed as JSON. Its TypeScript type comes from the [source](/webhooks/verification#typing-the-event). | -| `headers` | Request headers as a Web `Headers` object, with case-insensitive `get()` and `has()` methods. Credentials such as signatures are removed. | -| `endpoint` | The endpoint the delivery arrived on: `id`, `declaredId`, `tenantId`, `externalRef`, and the `metadata` you declared. | -| `ctx` | The same [run context](/context) that regular tasks receive. | - -`webhook()` also takes the options a [task](/tasks/overview) does, such as `queue`, `concurrency`, `machine`, `retry`, `maxDuration` and the lifecycle hooks. For example, to handle one delivery at a time: - -```ts -export const orders = webhook({ - id: "stripe-orders", - endpoint: stripe, - queue: { concurrencyLimit: 1 }, - retry: { maxAttempts: 5 }, - onEvent: async ({ event }) => { - // ... - }, -}); -``` - -The limit covers every delivery the task handles. To process each customer's events in order while different customers run in parallel, route them to an agent with [session routing](/webhooks/session-routing): deliveries with the same key land in one session and are handled one after another. - -`webhooks.endpoint.define` also takes a `description` and `metadata`. The metadata is passed to every subscriber as `endpoint.metadata`. The endpoint `id` can't start with `wh_`, which is reserved for the ids Trigger.dev generates. +Each subscriber has its own [filter](/webhooks/filters), so one delivery can reach several subscribers and skip the rest. An endpoint can have up to 25 subscribers. An endpoint with no subscribers still gets a URL, so you can register it with the provider before writing the handlers. See [Webhook tasks](/webhooks/webhook-tasks) for what a handler receives and the options it takes. diff --git a/docs/webhooks/webhook-tasks.mdx b/docs/webhooks/webhook-tasks.mdx new file mode 100644 index 00000000000..8f4063e1249 --- /dev/null +++ b/docs/webhooks/webhook-tasks.mdx @@ -0,0 +1,46 @@ +--- +title: "Webhook tasks" +sidebarTitle: "Webhook tasks" +description: "What a webhook() handler receives, the task options it takes, how to order deliveries per customer, and the options an endpoint takes." +--- + +**A webhook task is a [task](/tasks/overview) with an endpoint attached: `webhook()` runs `onEvent` once for each delivery that passes its [filter](/webhooks/filters).** + +## Handler arguments + +`onEvent` receives: + +| Argument | Value | +| --- | --- | +| `event` | The verified request body, parsed as JSON. Its TypeScript type comes from the [source](/webhooks/verification#typing-the-event). | +| `headers` | Request headers as a Web `Headers` object, with case-insensitive `get()` and `has()` methods. Credentials such as signatures are removed. | +| `endpoint` | The endpoint the delivery arrived on: `id`, `declaredId`, `tenantId`, `externalRef`, and the `metadata` you declared. | +| `ctx` | The same [run context](/context) that regular tasks receive. | + +## Task options + +`webhook()` also takes the options a [task](/tasks/overview) does, such as `queue`, `concurrency`, `machine`, `retry`, `maxDuration` and the lifecycle hooks. For example, to handle one delivery at a time: + +```ts /trigger/stripe-orders.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const stripe = webhooks.endpoint.define({ id: "stripe", source: webhooks.stripe() }); + +export const orders = webhook({ + id: "stripe-orders", + endpoint: stripe, + queue: { concurrencyLimit: 1 }, + retry: { maxAttempts: 5 }, + onEvent: async ({ event }) => { + // ... + }, +}); +``` + +## Ordering per customer + +The limit covers every delivery the task handles. To process each customer's events in order while different customers run in parallel, route them to an agent with [session routing](/webhooks/session-routing): deliveries with the same key land in one session and are handled one after another. + +## Endpoint options + +`webhooks.endpoint.define` also takes a `description` and `metadata`. The metadata is passed to every subscriber as `endpoint.metadata`. The endpoint `id` can't start with `wh_`, which is reserved for the ids Trigger.dev generates. From 5298c5b95cef7b146b4112a314350f105457d15e Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:45:17 +0000 Subject: [PATCH 16/37] docs(webhooks): reorder the sidebar to follow setup, handling, agents, then operations --- docs/docs.json | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 8fd19a6848b..7c854a96b58 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -173,8 +173,6 @@ "webhooks/overview", "webhooks/quick-start", "webhooks/how-it-works", - "webhooks/connect", - "webhooks/signing-secrets", { "group": "Providers", "pages": [ @@ -228,16 +226,18 @@ ] }, "webhooks/custom-providers", - "webhooks/verification", - "webhooks/deliveries", - "webhooks/filters", + "webhooks/connect", + "webhooks/signing-secrets", "webhooks/webhook-tasks", + "webhooks/filters", "webhooks/waiters", "webhooks/session-routing", "webhooks/channels", "webhooks/slack", "webhooks/linear", "webhooks/human-in-the-loop", + "webhooks/deliveries", + "webhooks/verification", "webhooks/own-handler", "webhooks/pricing-and-limits" ] From 0ed22abfdd7ea8bf6a0147fd954836e1ddd676c7 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:46:44 +0000 Subject: [PATCH 17/37] docs(webhooks): group the sidebar into Set up, Handle events, Agents and Operate --- docs/docs.json | 146 ++++++++++++++++++++++++++++--------------------- 1 file changed, 83 insertions(+), 63 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 7c854a96b58..cedb7712e5c 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -174,72 +174,92 @@ "webhooks/quick-start", "webhooks/how-it-works", { - "group": "Providers", + "group": "Set up", "pages": [ - "webhooks/providers", - "webhooks/providers/attio", - "webhooks/providers/autumn", - "webhooks/providers/brex", - "webhooks/providers/cal-com", - "webhooks/providers/calendly", - "webhooks/providers/clerk", - "webhooks/providers/composio", - "webhooks/providers/discord", - "webhooks/providers/docusign", - "webhooks/providers/elevenlabs", - "webhooks/providers/firecrawl", - "webhooks/providers/github", - "webhooks/providers/gitlab", - "webhooks/providers/granola", - "webhooks/providers/hookdeck", - "webhooks/providers/infisical", - "webhooks/providers/intercom", - "webhooks/providers/jira", - "webhooks/providers/langfuse", - "webhooks/providers/linear", - "webhooks/providers/loops", - "webhooks/providers/metronome", - "webhooks/providers/mux", - "webhooks/providers/notion", - "webhooks/providers/openai", - "webhooks/providers/pagerduty", - "webhooks/providers/plain", - "webhooks/providers/planetscale", - "webhooks/providers/recall-ai", - "webhooks/providers/replicate", - "webhooks/providers/resend", - "webhooks/providers/retell", - "webhooks/providers/sentry", - "webhooks/providers/shopify", - "webhooks/providers/slack", - "webhooks/providers/square", - "webhooks/providers/stripe", - "webhooks/providers/supabase", - "webhooks/providers/tailscale", - "webhooks/providers/typeform", - "webhooks/providers/vapi", - "webhooks/providers/vercel", - "webhooks/providers/whatsapp", - "webhooks/providers/workos", - "webhooks/providers/zendesk", - "webhooks/providers/zoom" + { + "group": "Providers", + "pages": [ + "webhooks/providers", + "webhooks/providers/attio", + "webhooks/providers/autumn", + "webhooks/providers/brex", + "webhooks/providers/cal-com", + "webhooks/providers/calendly", + "webhooks/providers/clerk", + "webhooks/providers/composio", + "webhooks/providers/discord", + "webhooks/providers/docusign", + "webhooks/providers/elevenlabs", + "webhooks/providers/firecrawl", + "webhooks/providers/github", + "webhooks/providers/gitlab", + "webhooks/providers/granola", + "webhooks/providers/hookdeck", + "webhooks/providers/infisical", + "webhooks/providers/intercom", + "webhooks/providers/jira", + "webhooks/providers/langfuse", + "webhooks/providers/linear", + "webhooks/providers/loops", + "webhooks/providers/metronome", + "webhooks/providers/mux", + "webhooks/providers/notion", + "webhooks/providers/openai", + "webhooks/providers/pagerduty", + "webhooks/providers/plain", + "webhooks/providers/planetscale", + "webhooks/providers/recall-ai", + "webhooks/providers/replicate", + "webhooks/providers/resend", + "webhooks/providers/retell", + "webhooks/providers/sentry", + "webhooks/providers/shopify", + "webhooks/providers/slack", + "webhooks/providers/square", + "webhooks/providers/stripe", + "webhooks/providers/supabase", + "webhooks/providers/tailscale", + "webhooks/providers/typeform", + "webhooks/providers/vapi", + "webhooks/providers/vercel", + "webhooks/providers/whatsapp", + "webhooks/providers/workos", + "webhooks/providers/zendesk", + "webhooks/providers/zoom" + ] + }, + "webhooks/custom-providers", + "webhooks/connect", + "webhooks/signing-secrets", + "webhooks/verification", + "webhooks/own-handler" + ] + }, + { + "group": "Handle events", + "pages": [ + "webhooks/webhook-tasks", + "webhooks/filters", + "webhooks/waiters" ] }, - "webhooks/custom-providers", - "webhooks/connect", - "webhooks/signing-secrets", - "webhooks/webhook-tasks", - "webhooks/filters", - "webhooks/waiters", - "webhooks/session-routing", - "webhooks/channels", - "webhooks/slack", - "webhooks/linear", - "webhooks/human-in-the-loop", - "webhooks/deliveries", - "webhooks/verification", - "webhooks/own-handler", - "webhooks/pricing-and-limits" + { + "group": "Agents", + "pages": [ + "webhooks/session-routing", + "webhooks/channels", + "webhooks/slack", + "webhooks/linear", + "webhooks/human-in-the-loop" + ] + }, + { + "group": "Operate", + "pages": [ + "webhooks/deliveries", + "webhooks/pricing-and-limits" + ] + } ] }, { From 64ff0187f9aafdf326f2f01d26a8edc7e6a90397 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:47:55 +0000 Subject: [PATCH 18/37] docs(webhooks): show webhook sections as visible sidebar headings --- docs/docs.json | 166 ++++++++++++++++++++++++------------------------- 1 file changed, 83 insertions(+), 83 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index cedb7712e5c..0ee002537eb 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -173,93 +173,93 @@ "webhooks/overview", "webhooks/quick-start", "webhooks/how-it-works", + "webhooks/own-handler" + ] + }, + { + "group": "Webhook providers", + "pages": [ { - "group": "Set up", - "pages": [ - { - "group": "Providers", - "pages": [ - "webhooks/providers", - "webhooks/providers/attio", - "webhooks/providers/autumn", - "webhooks/providers/brex", - "webhooks/providers/cal-com", - "webhooks/providers/calendly", - "webhooks/providers/clerk", - "webhooks/providers/composio", - "webhooks/providers/discord", - "webhooks/providers/docusign", - "webhooks/providers/elevenlabs", - "webhooks/providers/firecrawl", - "webhooks/providers/github", - "webhooks/providers/gitlab", - "webhooks/providers/granola", - "webhooks/providers/hookdeck", - "webhooks/providers/infisical", - "webhooks/providers/intercom", - "webhooks/providers/jira", - "webhooks/providers/langfuse", - "webhooks/providers/linear", - "webhooks/providers/loops", - "webhooks/providers/metronome", - "webhooks/providers/mux", - "webhooks/providers/notion", - "webhooks/providers/openai", - "webhooks/providers/pagerduty", - "webhooks/providers/plain", - "webhooks/providers/planetscale", - "webhooks/providers/recall-ai", - "webhooks/providers/replicate", - "webhooks/providers/resend", - "webhooks/providers/retell", - "webhooks/providers/sentry", - "webhooks/providers/shopify", - "webhooks/providers/slack", - "webhooks/providers/square", - "webhooks/providers/stripe", - "webhooks/providers/supabase", - "webhooks/providers/tailscale", - "webhooks/providers/typeform", - "webhooks/providers/vapi", - "webhooks/providers/vercel", - "webhooks/providers/whatsapp", - "webhooks/providers/workos", - "webhooks/providers/zendesk", - "webhooks/providers/zoom" - ] - }, - "webhooks/custom-providers", - "webhooks/connect", - "webhooks/signing-secrets", - "webhooks/verification", - "webhooks/own-handler" - ] - }, - { - "group": "Handle events", - "pages": [ - "webhooks/webhook-tasks", - "webhooks/filters", - "webhooks/waiters" - ] - }, - { - "group": "Agents", + "group": "Providers", "pages": [ - "webhooks/session-routing", - "webhooks/channels", - "webhooks/slack", - "webhooks/linear", - "webhooks/human-in-the-loop" + "webhooks/providers", + "webhooks/providers/attio", + "webhooks/providers/autumn", + "webhooks/providers/brex", + "webhooks/providers/cal-com", + "webhooks/providers/calendly", + "webhooks/providers/clerk", + "webhooks/providers/composio", + "webhooks/providers/discord", + "webhooks/providers/docusign", + "webhooks/providers/elevenlabs", + "webhooks/providers/firecrawl", + "webhooks/providers/github", + "webhooks/providers/gitlab", + "webhooks/providers/granola", + "webhooks/providers/hookdeck", + "webhooks/providers/infisical", + "webhooks/providers/intercom", + "webhooks/providers/jira", + "webhooks/providers/langfuse", + "webhooks/providers/linear", + "webhooks/providers/loops", + "webhooks/providers/metronome", + "webhooks/providers/mux", + "webhooks/providers/notion", + "webhooks/providers/openai", + "webhooks/providers/pagerduty", + "webhooks/providers/plain", + "webhooks/providers/planetscale", + "webhooks/providers/recall-ai", + "webhooks/providers/replicate", + "webhooks/providers/resend", + "webhooks/providers/retell", + "webhooks/providers/sentry", + "webhooks/providers/shopify", + "webhooks/providers/slack", + "webhooks/providers/square", + "webhooks/providers/stripe", + "webhooks/providers/supabase", + "webhooks/providers/tailscale", + "webhooks/providers/typeform", + "webhooks/providers/vapi", + "webhooks/providers/vercel", + "webhooks/providers/whatsapp", + "webhooks/providers/workos", + "webhooks/providers/zendesk", + "webhooks/providers/zoom" ] }, - { - "group": "Operate", - "pages": [ - "webhooks/deliveries", - "webhooks/pricing-and-limits" - ] - } + "webhooks/custom-providers", + "webhooks/connect", + "webhooks/signing-secrets", + "webhooks/verification" + ] + }, + { + "group": "Handling webhook events", + "pages": [ + "webhooks/webhook-tasks", + "webhooks/filters", + "webhooks/waiters" + ] + }, + { + "group": "Webhooks for AI agents", + "pages": [ + "webhooks/session-routing", + "webhooks/channels", + "webhooks/slack", + "webhooks/linear", + "webhooks/human-in-the-loop" + ] + }, + { + "group": "Webhook deliveries and limits", + "pages": [ + "webhooks/deliveries", + "webhooks/pricing-and-limits" ] }, { From e4b38c020d4c9afc4654a18ed34886c96a1c2f4e Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:48:39 +0000 Subject: [PATCH 19/37] docs(webhooks): keep one Webhooks section with expanded sub-groups --- docs/docs.json | 170 +++++++++++++++++++++++++------------------------ 1 file changed, 87 insertions(+), 83 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 0ee002537eb..277439044d4 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -173,93 +173,97 @@ "webhooks/overview", "webhooks/quick-start", "webhooks/how-it-works", - "webhooks/own-handler" - ] - }, - { - "group": "Webhook providers", - "pages": [ + "webhooks/own-handler", { - "group": "Providers", + "group": "Connect providers", + "expanded": true, "pages": [ - "webhooks/providers", - "webhooks/providers/attio", - "webhooks/providers/autumn", - "webhooks/providers/brex", - "webhooks/providers/cal-com", - "webhooks/providers/calendly", - "webhooks/providers/clerk", - "webhooks/providers/composio", - "webhooks/providers/discord", - "webhooks/providers/docusign", - "webhooks/providers/elevenlabs", - "webhooks/providers/firecrawl", - "webhooks/providers/github", - "webhooks/providers/gitlab", - "webhooks/providers/granola", - "webhooks/providers/hookdeck", - "webhooks/providers/infisical", - "webhooks/providers/intercom", - "webhooks/providers/jira", - "webhooks/providers/langfuse", - "webhooks/providers/linear", - "webhooks/providers/loops", - "webhooks/providers/metronome", - "webhooks/providers/mux", - "webhooks/providers/notion", - "webhooks/providers/openai", - "webhooks/providers/pagerduty", - "webhooks/providers/plain", - "webhooks/providers/planetscale", - "webhooks/providers/recall-ai", - "webhooks/providers/replicate", - "webhooks/providers/resend", - "webhooks/providers/retell", - "webhooks/providers/sentry", - "webhooks/providers/shopify", - "webhooks/providers/slack", - "webhooks/providers/square", - "webhooks/providers/stripe", - "webhooks/providers/supabase", - "webhooks/providers/tailscale", - "webhooks/providers/typeform", - "webhooks/providers/vapi", - "webhooks/providers/vercel", - "webhooks/providers/whatsapp", - "webhooks/providers/workos", - "webhooks/providers/zendesk", - "webhooks/providers/zoom" + { + "group": "Providers", + "pages": [ + "webhooks/providers", + "webhooks/providers/attio", + "webhooks/providers/autumn", + "webhooks/providers/brex", + "webhooks/providers/cal-com", + "webhooks/providers/calendly", + "webhooks/providers/clerk", + "webhooks/providers/composio", + "webhooks/providers/discord", + "webhooks/providers/docusign", + "webhooks/providers/elevenlabs", + "webhooks/providers/firecrawl", + "webhooks/providers/github", + "webhooks/providers/gitlab", + "webhooks/providers/granola", + "webhooks/providers/hookdeck", + "webhooks/providers/infisical", + "webhooks/providers/intercom", + "webhooks/providers/jira", + "webhooks/providers/langfuse", + "webhooks/providers/linear", + "webhooks/providers/loops", + "webhooks/providers/metronome", + "webhooks/providers/mux", + "webhooks/providers/notion", + "webhooks/providers/openai", + "webhooks/providers/pagerduty", + "webhooks/providers/plain", + "webhooks/providers/planetscale", + "webhooks/providers/recall-ai", + "webhooks/providers/replicate", + "webhooks/providers/resend", + "webhooks/providers/retell", + "webhooks/providers/sentry", + "webhooks/providers/shopify", + "webhooks/providers/slack", + "webhooks/providers/square", + "webhooks/providers/stripe", + "webhooks/providers/supabase", + "webhooks/providers/tailscale", + "webhooks/providers/typeform", + "webhooks/providers/vapi", + "webhooks/providers/vercel", + "webhooks/providers/whatsapp", + "webhooks/providers/workos", + "webhooks/providers/zendesk", + "webhooks/providers/zoom" + ] + }, + "webhooks/custom-providers", + "webhooks/connect", + "webhooks/signing-secrets", + "webhooks/verification" ] }, - "webhooks/custom-providers", - "webhooks/connect", - "webhooks/signing-secrets", - "webhooks/verification" - ] - }, - { - "group": "Handling webhook events", - "pages": [ - "webhooks/webhook-tasks", - "webhooks/filters", - "webhooks/waiters" - ] - }, - { - "group": "Webhooks for AI agents", - "pages": [ - "webhooks/session-routing", - "webhooks/channels", - "webhooks/slack", - "webhooks/linear", - "webhooks/human-in-the-loop" - ] - }, - { - "group": "Webhook deliveries and limits", - "pages": [ - "webhooks/deliveries", - "webhooks/pricing-and-limits" + { + "group": "Handle events", + "expanded": true, + "pages": [ + "webhooks/webhook-tasks", + "webhooks/filters", + "webhooks/waiters" + ] + }, + { + "group": "AI agents", + "expanded": true, + "pages": [ + "webhooks/session-routing", + "webhooks/channels", + "webhooks/slack", + "webhooks/linear", + "webhooks/human-in-the-loop" + ] + }, + { + "group": "Deliveries and limits", + "expanded": true, + "pages": [ + "webhooks/deliveries", + "webhooks/pricing-and-limits" + ] + } ] }, { From 7562a80889aec27485adb4bc4429c88045d5946b Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:49:54 +0000 Subject: [PATCH 20/37] docs(webhooks): rename sidebar groups to Providers and Built-in providers --- docs/docs.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 277439044d4..5909fa09423 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -175,11 +175,11 @@ "webhooks/how-it-works", "webhooks/own-handler", { - "group": "Connect providers", + "group": "Providers", "expanded": true, "pages": [ { - "group": "Providers", + "group": "Built-in providers", "pages": [ "webhooks/providers", "webhooks/providers/attio", From 9cdbfc1133e47486b4e5db3675ebcc956b518890 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:50:32 +0000 Subject: [PATCH 21/37] docs(webhooks): stop the own-handler description repeating its intro --- docs/webhooks/own-handler.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/webhooks/own-handler.mdx b/docs/webhooks/own-handler.mdx index b32f0a247bc..2658e91f90a 100644 --- a/docs/webhooks/own-handler.mdx +++ b/docs/webhooks/own-handler.mdx @@ -1,7 +1,7 @@ --- title: "Use your own webhook handler" sidebarTitle: "Using your own handler" -description: "Trigger.dev has built-in webhook endpoints, which we recommend for most projects. If you prefer to handle webhooks yourself, receive them in your own app and trigger runs from there." +description: "Receive webhooks in a route in your own app and trigger tasks from it with tasks.trigger()." --- **Trigger.dev has built-in webhook endpoints, and we recommend them for most projects.** They verify each provider's signature, drop duplicate retries, record every delivery, and route events to tasks, agents and waiting runs. See [Webhooks](/webhooks/overview). From fc930b07321d4672b9843c83c3b4449db9e9b268 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:52:26 +0000 Subject: [PATCH 22/37] docs(webhooks): say how human-in-the-loop uses webhooks --- docs/webhooks/human-in-the-loop.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/webhooks/human-in-the-loop.mdx b/docs/webhooks/human-in-the-loop.mdx index f166806f604..3a21ba92dcb 100644 --- a/docs/webhooks/human-in-the-loop.mdx +++ b/docs/webhooks/human-in-the-loop.mdx @@ -4,7 +4,7 @@ sidebarTitle: "Human-in-the-loop" description: "Pause an agent mid-turn to get a human decision from the channel (Slack approve/deny), then resume with the answer." --- -**An agent on a [channel](/webhooks/channels) can pause a turn to get a human decision, then resume once someone answers in the thread.** It posts controls into the conversation and picks up where it left off once someone clicks, with the decision merged into the turn. This is the channel counterpart of browser [human-in-the-loop](/ai-chat/patterns/human-in-the-loop): the same no-`execute` tool, but the controls live in Slack (or your own surface) instead of a React component. The [`slack()`](/webhooks/slack) connector ships Approve and Deny buttons out of the box. +**An agent on a [channel](/webhooks/channels) can pause a turn to get a human decision, then resume once someone answers in the thread.** It posts controls into the conversation and picks up where it left off once someone clicks, with the decision merged into the turn. The click arrives as a webhook on the same endpoint as the conversation's messages, and that delivery resumes the paused run. To pause a run until any other webhook arrives, use a [waiter](/webhooks/waiters). This is the channel counterpart of browser [human-in-the-loop](/ai-chat/patterns/human-in-the-loop): the same no-`execute` tool, but the controls live in Slack (or your own surface) instead of a React component. The [`slack()`](/webhooks/slack) connector ships Approve and Deny buttons out of the box. ## How it works From 31b786c04948581bfd3ed0bc831900420cb49f01 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 13:54:54 +0000 Subject: [PATCH 23/37] docs: move Slack, Linear, channels and channel human-in-the-loop into Agents Add a Channels group to the Agents section for the channel pages, and move Session routing into the Webhooks Handle events group. Page URLs are unchanged. --- docs/docs.json | 23 +++++++++++------------ docs/webhooks/channels.mdx | 2 +- docs/webhooks/human-in-the-loop.mdx | 2 +- 3 files changed, 13 insertions(+), 14 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 5909fa09423..5bb70fe55a5 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -134,6 +134,15 @@ "ai-chat/error-handling" ] }, + { + "group": "Channels", + "pages": [ + "webhooks/channels", + "webhooks/slack", + "webhooks/linear", + "webhooks/human-in-the-loop" + ] + }, { "group": "Patterns", "pages": [ @@ -242,18 +251,8 @@ "pages": [ "webhooks/webhook-tasks", "webhooks/filters", - "webhooks/waiters" - ] - }, - { - "group": "AI agents", - "expanded": true, - "pages": [ - "webhooks/session-routing", - "webhooks/channels", - "webhooks/slack", - "webhooks/linear", - "webhooks/human-in-the-loop" + "webhooks/waiters", + "webhooks/session-routing" ] }, { diff --git a/docs/webhooks/channels.mdx b/docs/webhooks/channels.mdx index 049b69f01ea..1b48b899d90 100644 --- a/docs/webhooks/channels.mdx +++ b/docs/webhooks/channels.mdx @@ -1,7 +1,7 @@ --- title: "Channels (chat frontends)" description: "Point Slack (or any chat surface) at an agent: messages become turns and replies post back." -sidebarTitle: "Channels" +sidebarTitle: "Overview" --- A [session route](/webhooks/session-routing) delivers a verified event to an agent as an [action](/ai-chat/actions): the agent reacts, and the response is a side effect. A **channel** is the other half: the webhook IS the chat surface. Inbound messages become **turns** (the normal `run()` loop), and the agent's reply is posted **back** to the surface. A Slack thread becomes a real conversation with the agent, exactly like the browser chat, just a different frontend. diff --git a/docs/webhooks/human-in-the-loop.mdx b/docs/webhooks/human-in-the-loop.mdx index 3a21ba92dcb..c28066c452b 100644 --- a/docs/webhooks/human-in-the-loop.mdx +++ b/docs/webhooks/human-in-the-loop.mdx @@ -1,5 +1,5 @@ --- -title: "Human-in-the-loop" +title: "Human-in-the-loop over a channel" sidebarTitle: "Human-in-the-loop" description: "Pause an agent mid-turn to get a human decision from the channel (Slack approve/deny), then resume with the answer." --- From 75fa16d2e5a358be188b86684a54a93ebd620a2b Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 15:21:14 +0000 Subject: [PATCH 24/37] docs: restore webhook SEO targets after restructure Add Named providers and Custom providers sections to Verification so old /webhooks/sources anchors land on them, expand the Stripe provider page with Dashboard setup, local testing and an own-route section, and redirect /examples/stripe-webhook and /examples/hookdeck-webhook directly. --- docs/docs.json | 8 +++++ docs/webhooks/own-handler.mdx | 2 ++ docs/webhooks/providers/stripe.mdx | 55 ++++++++++++++++++++++-------- docs/webhooks/verification.mdx | 10 +++++- 4 files changed, 59 insertions(+), 16 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 5bb70fe55a5..836f60d616d 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -901,6 +901,14 @@ "source": "/guides/examples/hookdeck-webhook", "destination": "/webhooks/providers/hookdeck" }, + { + "source": "/examples/stripe-webhook", + "destination": "/webhooks/providers/stripe" + }, + { + "source": "/examples/hookdeck-webhook", + "destination": "/webhooks/providers/hookdeck" + }, { "source": "/webhooks/private-beta", "destination": "/webhooks/overview", diff --git a/docs/webhooks/own-handler.mdx b/docs/webhooks/own-handler.mdx index 2658e91f90a..3ab5d15f142 100644 --- a/docs/webhooks/own-handler.mdx +++ b/docs/webhooks/own-handler.mdx @@ -48,6 +48,8 @@ export async function POST(request: Request) { Return quickly: the task runs in the background, so the provider gets its response before the work starts. +Set `TRIGGER_SECRET_KEY` in your app to a named [**Trigger only**](/apikeys) API key from the Trigger.dev environment the app uses, so the route can trigger tasks but do nothing else. + ## Framework guides diff --git a/docs/webhooks/providers/stripe.mdx b/docs/webhooks/providers/stripe.mdx index d1587a72f98..34434400467 100644 --- a/docs/webhooks/providers/stripe.mdx +++ b/docs/webhooks/providers/stripe.mdx @@ -1,10 +1,10 @@ --- -title: "Stripe webhooks" +title: "Receive and verify Stripe webhooks" sidebarTitle: "Stripe" -description: "Receive Stripe webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Stripe, and how to set the signing credential." +description: "Verify Stripe's webhook signature and run a Trigger.dev task for each Stripe event, such as checkout.session.completed. Register the endpoint in Stripe, set the whsec_ signing secret, and filter by event type." --- -**`webhooks.stripe()` verifies Stripe's signature on every request, so subscribers only receive genuine Stripe events.** +**`webhooks.stripe()` verifies the `stripe-signature` header on every request, so subscribers only receive genuine Stripe events.** ```ts /trigger/stripe.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -14,12 +14,12 @@ export const stripe = webhooks.endpoint.define({ source: webhooks.stripe(), }); -export const stripeEvents = webhook({ - id: "stripe-events", +export const fulfillCheckout = webhook({ + id: "fulfill-checkout", endpoint: stripe, filter: "event.type == 'checkout.session.completed'", onEvent: async ({ event }) => { - console.log(event); + console.log("Checkout completed", event.data.object.id); }, }); ``` @@ -28,23 +28,33 @@ export const stripeEvents = webhook({ | --- | --- | | Source | `webhooks.stripe()` | | Verification | HMAC-SHA256 in `stripe-signature`, with a timestamp tolerance | -| Credential | Signing secret issued by Stripe | +| Credential | Signing secret issued by Stripe (starts with `whsec_`) | | Event type | `event.type` | | Stripe docs | [Stripe webhook docs](https://docs.stripe.com/webhooks) | ## Set up Stripe 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Create the webhook endpoint with the Stripe CLI or API, not the Dashboard, so you can read the signing secret from the response: +2. In the Stripe Dashboard, open the **Webhooks** tab in Workbench and choose **Create an event destination**. Choose the **Snapshot** payload format, select the events you want, choose **Webhook endpoint** and paste the Webhook URL. +3. On the destination's settings page, choose **Reveal secret** and copy the signing secret. +4. Choose **Set signing secret** on the Trigger.dev endpoint and paste the secret. +5. Use a test mode destination for dev and staging environments and a live mode destination for production. Each has its own signing secret. - ```bash - stripe webhook_endpoints create -d url="" -d "enabled_events[]=checkout.session.completed" - ``` +To create the destination from the Stripe CLI instead, the response's `secret` field is the signing secret: - The response's `secret` field is the signing secret; Stripe only returns it when the endpoint is created. -3. Choose **Set signing secret** on the Trigger.dev endpoint and paste the secret. -4. Use a test mode key for dev and staging environments and a live mode key for production. -5. Send a test event from Stripe, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. +```bash +stripe webhook_endpoints create -d url="" -d "enabled_events[]=checkout.session.completed" +``` + +## Test locally + +Your dev environment has its own Webhook URL, so you don't need `stripe listen` or a tunnel. With `trigger dev` running and a test mode destination pointing at the dev URL, send a test event with the Stripe CLI: + +```bash +stripe trigger checkout.session.completed +``` + +The delivery appears on the endpoint's **Deliveries** tab with a link to the run it started. You can also send a sample event from the endpoint's **Test** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. ## Typing the event @@ -59,3 +69,18 @@ export const stripe = webhooks.endpoint.define({ source: webhooks.stripe(), }); ``` + +## Handle Stripe webhooks in your own route + +If you already receive Stripe webhooks in your app, verify them with `stripe.webhooks.constructEvent()` and trigger a task from the route with `tasks.trigger()`. See [Use your own webhook handler](/webhooks/own-handler) for a Next.js example. + +## Next steps + + + + Run each subscriber only for the Stripe events it handles. + + + Pause a run until a matching Stripe event arrives. + + diff --git a/docs/webhooks/verification.mdx b/docs/webhooks/verification.mdx index 02958898d88..1a047ea4142 100644 --- a/docs/webhooks/verification.mdx +++ b/docs/webhooks/verification.mdx @@ -73,7 +73,7 @@ export const composioEvents = webhook({ -The available presets are `stripe()`, `github()`, `svix()`, `standardWebhooks()`, `square()`, and `discord()`. More than 40 named providers build on the same verifiers; see [Providers](/webhooks/providers) for the full list and each provider's setup. +The available presets are `stripe()`, `github()`, `svix()`, `standardWebhooks()`, `square()`, and `discord()`. ### Svix and Standard Webhooks @@ -86,6 +86,14 @@ The available presets are `stripe()`, `github()`, `svix()`, `standardWebhooks()` Named sources such as `webhooks.clerk()` and `webhooks.composio()` select the corresponding configuration. +## Named providers + +More than 40 named providers, such as `webhooks.firecrawl()`, `webhooks.linear()` and `webhooks.hookdeck()`, build on the same verifiers. [Providers](/webhooks/providers) lists every one, with where to register the URL and set the signing secret. + +## Custom providers + +For a provider without a built-in source, describe its signature scheme with `webhooks.custom()`. See [Custom providers](/webhooks/custom-providers) for the verification schemes and options. + ## Endpoint validation Some sources also define a response for the provider's endpoint-validation request. These requests don't create deliveries or task runs. From d57946c567a4f8d7b6878f0e252dbd0802c0de29 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 15:30:46 +0000 Subject: [PATCH 25/37] docs: tidy webhook terms, duplicates and links Use provider for the service and source for the code value, keep the credential and subscriber tables in one place each, complete the deduplication key table, drop Stripe from the examples cards, rename stale webhook handler cards, and update dead or moved provider docs links. --- docs/guides/frameworks/remix.mdx | 2 +- .../supabase-edge-functions-database-webhooks.mdx | 2 +- docs/snippets/examples-cards.mdx | 4 ++-- docs/snippets/vercel-docs-cards.mdx | 2 +- docs/webhooks/connect.mdx | 13 +++++-------- docs/webhooks/custom-providers.mdx | 6 +++--- docs/webhooks/deliveries.mdx | 12 ++++++------ docs/webhooks/how-it-works.mdx | 10 ++-------- docs/webhooks/overview.mdx | 2 +- docs/webhooks/providers.mdx | 4 ++-- docs/webhooks/providers/brex.mdx | 2 +- docs/webhooks/providers/calendly.mdx | 4 ++-- docs/webhooks/providers/clerk.mdx | 2 +- docs/webhooks/providers/openai.mdx | 2 +- docs/webhooks/providers/pagerduty.mdx | 4 ++-- docs/webhooks/providers/plain.mdx | 2 +- docs/webhooks/providers/resend.mdx | 2 +- docs/webhooks/providers/sentry.mdx | 4 ++-- docs/webhooks/providers/tailscale.mdx | 2 +- docs/webhooks/quick-start.mdx | 2 +- docs/webhooks/verification.mdx | 2 +- 21 files changed, 38 insertions(+), 47 deletions(-) diff --git a/docs/guides/frameworks/remix.mdx b/docs/guides/frameworks/remix.mdx index 8ea5f281c3e..a6d60b5bb23 100644 --- a/docs/guides/frameworks/remix.mdx +++ b/docs/guides/frameworks/remix.mdx @@ -207,7 +207,7 @@ The `@trigger.dev/react-hooks` package lets you subscribe to task runs from your ## Additional resources for Remix diff --git a/docs/guides/frameworks/supabase-edge-functions-database-webhooks.mdx b/docs/guides/frameworks/supabase-edge-functions-database-webhooks.mdx index 0d957cc45b8..afa42b3cc34 100644 --- a/docs/guides/frameworks/supabase-edge-functions-database-webhooks.mdx +++ b/docs/guides/frameworks/supabase-edge-functions-database-webhooks.mdx @@ -15,7 +15,7 @@ import SupabaseAuthInfo from "/snippets/supabase-auth-info.mdx"; Trigger.dev has built-in webhook endpoints that verify and route events for you. See - [Webhooks](/webhooks/overview), including a [Supabase source](/webhooks/providers/supabase) for database webhooks. This guide is for when you want to handle webhooks in your own app and trigger tasks yourself. + [Webhooks](/webhooks/overview), including a [Supabase provider](/webhooks/providers/supabase) for database webhooks. This guide is for when you want to handle webhooks in your own app and trigger tasks yourself. ## Overview diff --git a/docs/snippets/examples-cards.mdx b/docs/snippets/examples-cards.mdx index 6345ec1684d..15d2dfadba0 100644 --- a/docs/snippets/examples-cards.mdx +++ b/docs/snippets/examples-cards.mdx @@ -3,11 +3,11 @@ Detailed guides for setting up Trigger.dev with popular frameworks and services, including - Next.js, Remix, Supabase, Stripe and more. + Next.js, Remix, Supabase and more. Task code you can copy and paste to use in your own projects, including OpenAI, Vercel AI SDK, - Deepgram, FFmpeg, Puppeteer, Stripe, Supabase and more. + Deepgram, FFmpeg, Puppeteer, Supabase and more. Receive webhooks from Stripe, GitHub, Firecrawl, Supabase and 40+ other providers on hosted diff --git a/docs/snippets/vercel-docs-cards.mdx b/docs/snippets/vercel-docs-cards.mdx index ea909ac0bd6..92565f723b9 100644 --- a/docs/snippets/vercel-docs-cards.mdx +++ b/docs/snippets/vercel-docs-cards.mdx @@ -8,7 +8,7 @@ diff --git a/docs/webhooks/connect.mdx b/docs/webhooks/connect.mdx index 5c6d8b27150..3044f6c9dc8 100644 --- a/docs/webhooks/connect.mdx +++ b/docs/webhooks/connect.mdx @@ -4,7 +4,7 @@ description: "Register an endpoint's URL and signing credential with the provide sidebarTitle: "Connect a provider" --- -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 source](/webhooks/custom-providers) first. +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. 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. @@ -15,13 +15,10 @@ Deploy the project or start `trigger dev` first. Once the CLI finds the endpoint Open the endpoint from the Webhooks page and copy the **Webhook URL**. - Add the URL as the webhook destination in your provider's dashboard and select the events your subscribers need. The provider's setup determines where the verification credential comes from: - - | Provider setup | Action | - | --- | --- | - | 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. | - | 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. | - | 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. | + Add the URL as the webhook destination in your provider's dashboard and select the events your subscribers need. + + + 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). Set the credential before sending a test event or asking the provider to validate the URL. diff --git a/docs/webhooks/custom-providers.mdx b/docs/webhooks/custom-providers.mdx index eae6eefde05..f3c3bb76e64 100644 --- a/docs/webhooks/custom-providers.mdx +++ b/docs/webhooks/custom-providers.mdx @@ -4,9 +4,9 @@ sidebarTitle: "Custom providers" 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()." --- -**`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 source. +**`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. -## Define a custom source +## Define a custom provider 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: @@ -70,7 +70,7 @@ export const commands = webhook({ ## Verification schemes -Custom sources support these schemes: +`webhooks.custom()` supports these schemes: | Scheme | Verification | | --- | --- | diff --git a/docs/webhooks/deliveries.mdx b/docs/webhooks/deliveries.mdx index 978a9e3001e..96954c69b4a 100644 --- a/docs/webhooks/deliveries.mdx +++ b/docs/webhooks/deliveries.mdx @@ -81,20 +81,20 @@ Trigger.dev uses the endpoint and idempotency key to deduplicate incoming events | What is deduplicated | Window | | --- | --- | | Delivery records | Six hours by default. | -| Task runs | Three days for Stripe; one day for other sources. | +| Task runs | Three days for Stripe; one day for other providers. | A retry after the delivery window expires can create another delivery record. If the task-run idempotency window is still active, routing returns the existing run instead of starting another one. When the source maps a provider event ID, that ID becomes the key, so the provider's own retries of an event are recognised as duplicates: -| Key | Sources | +| Key | Providers | | --- | --- | -| A header | GitHub (`X-GitHub-Delivery`), Svix and Autumn (`svix-id`), Standard Webhooks, Loops and Granola (`webhook-id`), Linear (`Linear-Delivery`), PagerDuty (`X-Webhook-Id`), Jira (`X-Atlassian-Webhook-Identifier`), Zendesk (`X-Zendesk-Webhook-Invocation-Id`), Attio (`Idempotency-Key`), Shopify (`X-Shopify-Webhook-Id`), Hookdeck (`X-Hookdeck-Eventid`, or `-eventid` with a custom header prefix) | -| A body field | Stripe, Notion, Vercel, Intercom, WorkOS, Metronome, Mux, Langfuse and Plain (`id`), Square, Slack and Typeform (`event_id`), Firecrawl (`webhookId`) | +| A header | GitHub (`X-GitHub-Delivery`); Svix, Clerk, Resend, Brex and Autumn (`svix-id`); Standard Webhooks, OpenAI, Replicate, Recall.ai, Composio, Loops and Granola (`webhook-id`); Linear (`Linear-Delivery`); PagerDuty (`X-Webhook-Id`); Jira (`X-Atlassian-Webhook-Identifier`); Zendesk (`X-Zendesk-Webhook-Invocation-Id`); Attio (`Idempotency-Key`); Shopify (`X-Shopify-Webhook-Id`); Hookdeck (`X-Hookdeck-Eventid`, or `-eventid` with a custom header prefix) | +| A body field | Stripe, Notion, Vercel, Intercom, WorkOS, Metronome, Mux, Langfuse and Plain (`id`); Square, Slack and Typeform (`event_id`); Firecrawl (`webhookId`) | -The other built-in providers (Zoom, Calendly, Sentry, DocuSign, ElevenLabs, Vapi, Retell, Tailscale, Infisical, PlanetScale, Supabase, Discord) use the fallback below. +The other built-in providers (Calendly, Cal.com, Sentry, DocuSign, ElevenLabs, Vapi, Retell, Tailscale, Infisical, PlanetScale, Supabase, Discord, GitLab and WhatsApp) use the fallback below. -If the source doesn't map an event ID, the key is derived from the raw body, timestamp, and signature. A retry with a different timestamp or signature can therefore produce a different key. For a [custom source](/webhooks/custom-providers), set `idempotencyField` to a stable event identifier when the provider supplies one. +If the source doesn't map an event ID, the key is derived from the raw body, timestamp, and signature. A retry with a different timestamp or signature can therefore produce a different key. For a [custom provider](/webhooks/custom-providers), set `idempotencyField` to a stable event identifier when the provider supplies one. ## Verification and recording diff --git a/docs/webhooks/how-it-works.mdx b/docs/webhooks/how-it-works.mdx index edacd282e07..efd2157d3a1 100644 --- a/docs/webhooks/how-it-works.mdx +++ b/docs/webhooks/how-it-works.mdx @@ -36,13 +36,7 @@ Each environment gets its own URL for each endpoint. Your dev environment has it ## One endpoint, many subscribers -A provider account usually needs one URL, so every subscriber shares the endpoint. One delivery can reach up to 25 subscribers: - -| Subscriber | What a matching delivery does | -| --- | --- | -| Task, declared with `webhook()` | Starts a run with the event as its payload. | -| [Waiter](/webhooks/waiters) | Resumes a run that paused until this event arrived. | -| Agent session, via [session routing](/webhooks/session-routing) or a [channel](/webhooks/channels) | Delivers the event to the right conversation, so the agent acts with its full history. | +A provider account usually needs one URL, so every subscriber shares the endpoint. One delivery can start task runs, resume [waiting runs](/webhooks/waiters) and reach agent sessions at the same time. See [What can subscribe](/webhooks/overview#what-can-subscribe). A delivery that no filter matches is recorded as `FILTERED` and starts no run, so it costs nothing. See [Pricing and limits](/webhooks/pricing-and-limits). @@ -55,7 +49,7 @@ Duplicates are caught in two places: A waiter completes once, and an agent session skips an event it has already received. A resend after the retry window, such as resending an event from the provider's dashboard a week later, starts a new run, so keep side effects in your handler idempotent. -If a provider sends no event ID, the key comes from the body, timestamp and signature. See [Deduplication](/webhooks/deliveries#deduplication). +See [Deduplication](/webhooks/deliveries#deduplication) for the windows and the key each provider uses. ## Every delivery is recorded diff --git a/docs/webhooks/overview.mdx b/docs/webhooks/overview.mdx index 6bdeee30501..6964cc748d2 100644 --- a/docs/webhooks/overview.mdx +++ b/docs/webhooks/overview.mdx @@ -57,7 +57,7 @@ Stripe gets one URL. A checkout event runs `fulfill-order`, a refund runs `recor | Chat frontend | a [channel connector](/webhooks/channels) such as `chat.channels.custom({ endpoint })` | Runs a turn on the conversation's session and posts the reply back. | | Waiting run | [`webhooks.waiter.create(endpoint, { match })`](/webhooks/waiters) | Resumes a run that is waiting for this event. | -Each subscriber has its own [filter](/webhooks/filters), so one delivery can reach several subscribers and skip the rest. An endpoint can have up to 25 subscribers. An endpoint with no subscribers still gets a URL, so you can register it with the provider before writing the handlers. See [Webhook tasks](/webhooks/webhook-tasks) for what a handler receives and the options it takes. +Each subscriber has its own [filter](/webhooks/filters), so one delivery can reach several subscribers and skip the rest. An endpoint can have up to 25 tasks, agent sessions and channels subscribed; waiting runs don't count toward that limit. An endpoint with no subscribers still gets a URL, so you can register it with the provider before writing the handlers. See [Webhook tasks](/webhooks/webhook-tasks) for what a handler receives and the options it takes. diff --git a/docs/webhooks/providers.mdx b/docs/webhooks/providers.mdx index 028e74b6186..f8049bb5b9f 100644 --- a/docs/webhooks/providers.mdx +++ b/docs/webhooks/providers.mdx @@ -1,7 +1,7 @@ --- title: "Webhook providers" sidebarTitle: "All providers" -description: "Every built-in webhook source, with its SDK function, the credential it verifies with, and a setup page for each provider." +description: "Every built-in webhook provider, with its SDK function, the credential it verifies with, and a setup page for each provider." --- **Each built-in provider has a source function that verifies its signature scheme, so you declare the endpoint with one function call and set one credential.** Every provider below has a page with the source, where to register the URL, and how to set the credential. @@ -55,4 +55,4 @@ description: "Every built-in webhook source, with its SDK function, the credenti | [Zendesk](/webhooks/providers/zendesk) | `webhooks.zendesk()` | You generate it, or the provider issues it | | [Zoom](/webhooks/providers/zoom) | `webhooks.zoom()` | Issued by the provider | -For a provider that isn't listed, define a [custom source](/webhooks/custom-providers). For providers that sign with Svix or Standard Webhooks, `webhooks.svix()` and `webhooks.standardWebhooks()` also work; see [Sources and verification](/webhooks/verification#svix-and-standard-webhooks). +For a provider that isn't listed, define a [custom provider](/webhooks/custom-providers). For providers that sign with Svix or Standard Webhooks, `webhooks.svix()` and `webhooks.standardWebhooks()` also work; see [Verification](/webhooks/verification#svix-and-standard-webhooks). diff --git a/docs/webhooks/providers/brex.mdx b/docs/webhooks/providers/brex.mdx index 390fa5688f8..7d92f6c5b08 100644 --- a/docs/webhooks/providers/brex.mdx +++ b/docs/webhooks/providers/brex.mdx @@ -31,7 +31,7 @@ To run a subscriber only for some events, add a [filter](/webhooks/filters) on ` | Verification | Svix (`svix-id`, `svix-timestamp`, `svix-signature`) | | Credential | Signing secret issued by Brex | | Event type | `event.event_type` | -| Brex docs | [Brex webhook docs](https://developer.brex.com/docs/webhooks/) | +| Brex docs | [Brex webhook docs](https://developer.brex.com/guides/webhooks) | ## Set up Brex diff --git a/docs/webhooks/providers/calendly.mdx b/docs/webhooks/providers/calendly.mdx index 9306074a957..08f3dcfe8c7 100644 --- a/docs/webhooks/providers/calendly.mdx +++ b/docs/webhooks/providers/calendly.mdx @@ -31,11 +31,11 @@ To run a subscriber only for some events, add a [filter](/webhooks/filters) on ` | Verification | HMAC-SHA256 in `calendly-webhook-signature` | | Credential | Signing secret issued by Calendly | | Event type | `event.event` | -| Calendly docs | [Calendly webhook docs](https://developer.calendly.com/api-docs/4c305798a61d3-webhook-signatures) | +| Calendly docs | [Calendly webhook docs](https://developer.calendly.com/api-docs/overview/webhooks/webhook-signatures) | ## Set up Calendly 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as a webhook in Calendly and select the events your subscribers need. See Calendly's [webhook docs](https://developer.calendly.com/api-docs/4c305798a61d3-webhook-signatures) for where its webhook settings are. +2. Add the webhook URL as a webhook in Calendly and select the events your subscribers need. See Calendly's [webhook docs](https://developer.calendly.com/api-docs/overview/webhooks/webhook-signatures) for where its webhook settings are. 3. Copy the signing secret Calendly shows for the webhook, then choose **Set signing secret** on the Trigger.dev endpoint. 4. Send a test event from Calendly, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/clerk.mdx b/docs/webhooks/providers/clerk.mdx index 27344e4421e..473eed4df7e 100644 --- a/docs/webhooks/providers/clerk.mdx +++ b/docs/webhooks/providers/clerk.mdx @@ -30,7 +30,7 @@ export const clerkEvents = webhook({ | Verification | Svix (`svix-id`, `svix-timestamp`, `svix-signature`) | | Credential | Signing secret issued by Clerk | | Event type | `event.type` | -| Clerk docs | [Clerk webhook docs](https://clerk.com/docs/integrations/webhooks/overview) | +| Clerk docs | [Clerk webhook docs](https://clerk.com/docs/guides/development/webhooks/overview) | ## Set up Clerk diff --git a/docs/webhooks/providers/openai.mdx b/docs/webhooks/providers/openai.mdx index 9e75d56de47..df02aca162e 100644 --- a/docs/webhooks/providers/openai.mdx +++ b/docs/webhooks/providers/openai.mdx @@ -30,7 +30,7 @@ export const openaiEvents = webhook({ | Verification | Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`) | | Credential | Signing secret issued by OpenAI | | Event type | `event.type` | -| OpenAI docs | [OpenAI webhook docs](https://platform.openai.com/docs/guides/webhooks) | +| OpenAI docs | [OpenAI webhook docs](https://developers.openai.com/api/docs/guides/webhooks) | ## Set up OpenAI diff --git a/docs/webhooks/providers/pagerduty.mdx b/docs/webhooks/providers/pagerduty.mdx index 14b4ae20180..563101bf179 100644 --- a/docs/webhooks/providers/pagerduty.mdx +++ b/docs/webhooks/providers/pagerduty.mdx @@ -30,11 +30,11 @@ export const pagerdutyEvents = webhook({ | Verification | HMAC-SHA256 in `x-pagerduty-signature` | | Credential | Signing secret you generate on Trigger.dev, or one issued by PagerDuty | | Event type | `event.event.event_type` | -| PagerDuty docs | [PagerDuty webhook docs](https://developer.pagerduty.com/docs/webhooks/webhook-signatures/) | +| PagerDuty docs | [PagerDuty webhook docs](https://docs.pagerduty.com/developer/verifying-webhook-signatures) | ## Set up PagerDuty 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as a webhook in PagerDuty and select the events your subscribers need. See PagerDuty's [webhook docs](https://developer.pagerduty.com/docs/webhooks/webhook-signatures/) for where its webhook settings are. +2. Add the webhook URL as a webhook in PagerDuty and select the events your subscribers need. See PagerDuty's [webhook docs](https://docs.pagerduty.com/developer/verifying-webhook-signatures) for where its webhook settings are. 3. If PagerDuty shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If PagerDuty asks you for a secret, choose **Generate secret** on the endpoint and paste the value into PagerDuty. 4. Send a test event from PagerDuty, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/plain.mdx b/docs/webhooks/providers/plain.mdx index 4c10a6260c3..3631be341d9 100644 --- a/docs/webhooks/providers/plain.mdx +++ b/docs/webhooks/providers/plain.mdx @@ -30,7 +30,7 @@ export const plainEvents = webhook({ | Verification | HMAC-SHA256 in `plain-request-signature` | | Credential | Signing secret issued by Plain | | Event type | `event.type` | -| Plain docs | [Plain webhook docs](https://www.plain.com/docs/api-reference/webhooks) | +| Plain docs | [Plain webhook docs](https://www.plain.com/docs/webhooks) | ## Set up Plain diff --git a/docs/webhooks/providers/resend.mdx b/docs/webhooks/providers/resend.mdx index d296e15230c..2d5b91d65ca 100644 --- a/docs/webhooks/providers/resend.mdx +++ b/docs/webhooks/providers/resend.mdx @@ -30,7 +30,7 @@ export const resendEvents = webhook({ | Verification | Svix (`svix-id`, `svix-timestamp`, `svix-signature`) | | Credential | Signing secret issued by Resend | | Event type | `event.type` | -| Resend docs | [Resend webhook docs](https://resend.com/docs/dashboard/webhooks/introduction) | +| Resend docs | [Resend webhook docs](https://resend.com/docs/webhooks/introduction) | ## Set up Resend diff --git a/docs/webhooks/providers/sentry.mdx b/docs/webhooks/providers/sentry.mdx index 6eae8a2e4fe..f0dbeeaf7c6 100644 --- a/docs/webhooks/providers/sentry.mdx +++ b/docs/webhooks/providers/sentry.mdx @@ -31,11 +31,11 @@ To run a subscriber only for some events, add a [filter](/webhooks/filters) on ` | Verification | HMAC-SHA256 in `sentry-hook-signature` | | Credential | Signing secret you generate on Trigger.dev, or one issued by Sentry | | Event type | `header.sentry-hook-resource` | -| Sentry docs | [Sentry webhook docs](https://docs.sentry.io/product/integrations/integration-platform/webhooks/) | +| Sentry docs | [Sentry webhook docs](https://docs.sentry.io/integrations/integration-platform/webhooks/) | ## Set up Sentry 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as a webhook in Sentry and select the events your subscribers need. See Sentry's [webhook docs](https://docs.sentry.io/product/integrations/integration-platform/webhooks/) for where its webhook settings are. +2. Add the webhook URL as a webhook in Sentry and select the events your subscribers need. See Sentry's [webhook docs](https://docs.sentry.io/integrations/integration-platform/webhooks/) for where its webhook settings are. 3. If Sentry shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Sentry asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Sentry. 4. Send a test event from Sentry, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/tailscale.mdx b/docs/webhooks/providers/tailscale.mdx index 143808abbe5..c2e57c45541 100644 --- a/docs/webhooks/providers/tailscale.mdx +++ b/docs/webhooks/providers/tailscale.mdx @@ -29,7 +29,7 @@ export const tailscaleEvents = webhook({ | Source | `webhooks.tailscale()` | | Verification | HMAC-SHA256 in `tailscale-webhook-signature` | | Credential | Signing secret issued by Tailscale | -| Tailscale docs | [Tailscale webhook docs](https://tailscale.com/kb/1213/webhooks) | +| Tailscale docs | [Tailscale webhook docs](https://tailscale.com/docs/features/webhooks) | ## Set up Tailscale diff --git a/docs/webhooks/quick-start.mdx b/docs/webhooks/quick-start.mdx index 591f256ef8e..b57a44982f2 100644 --- a/docs/webhooks/quick-start.mdx +++ b/docs/webhooks/quick-start.mdx @@ -6,7 +6,7 @@ description: "Declare a hosted webhook endpoint, run it in dev, and see your fir Install the SDK, declare an endpoint with a subscriber, and send it a test event. By the end, a verified delivery starts a run of your task. -This guide uses the [GitHub source](/webhooks/providers/github) because you generate its signing secret on Trigger.dev, so you don't need a GitHub account to finish it. The steps are the same for every [provider](/webhooks/providers). +This guide uses the [GitHub provider](/webhooks/providers/github) because you generate its signing secret on Trigger.dev, so you don't need a GitHub account to finish it. The steps are the same for every [provider](/webhooks/providers). diff --git a/docs/webhooks/verification.mdx b/docs/webhooks/verification.mdx index 1a047ea4142..6b143aac904 100644 --- a/docs/webhooks/verification.mdx +++ b/docs/webhooks/verification.mdx @@ -134,4 +134,4 @@ For `webhooks.custom()`, pass your own event type as `T`. The endpoint's even 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). -To verify a provider that isn't built in, choose a scheme in a [custom source](/webhooks/custom-providers#verification-schemes). +To verify a provider that isn't built in, choose a scheme for a [custom provider](/webhooks/custom-providers#verification-schemes). From c60188b2146f63d2c1d58dd1aee8ebbc247c548a Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 15:36:16 +0000 Subject: [PATCH 26/37] docs: correct webhook provider setup steps and delivery details Fix the removed-headers, channel replay targetId and deliveryId notes, set Discord's public key before saving the URL, and rewrite setup for Vapi, Replicate, Retell AI, Brex, Calendly, DocuSign, Autumn and Recall.ai from each provider's current docs. --- docs/webhooks/deliveries.mdx | 2 +- docs/webhooks/filters.mdx | 2 +- docs/webhooks/providers.mdx | 8 ++++---- docs/webhooks/providers/autumn.mdx | 7 +++---- docs/webhooks/providers/brex.mdx | 6 +++--- docs/webhooks/providers/calendly.mdx | 6 +++--- docs/webhooks/providers/discord.mdx | 4 ++-- docs/webhooks/providers/docusign.mdx | 6 +++--- docs/webhooks/providers/recall-ai.mdx | 19 ++++++++++++++++--- docs/webhooks/providers/replicate.mdx | 6 +++--- docs/webhooks/providers/retell.mdx | 6 +++--- docs/webhooks/providers/slack.mdx | 2 +- docs/webhooks/providers/vapi.mdx | 14 ++++++++++---- docs/webhooks/session-routing.mdx | 2 +- docs/webhooks/waiters.mdx | 4 ++-- docs/webhooks/webhook-tasks.mdx | 2 +- 16 files changed, 57 insertions(+), 39 deletions(-) diff --git a/docs/webhooks/deliveries.mdx b/docs/webhooks/deliveries.mdx index 96954c69b4a..387cc9fe14e 100644 --- a/docs/webhooks/deliveries.mdx +++ b/docs/webhooks/deliveries.mdx @@ -58,7 +58,7 @@ curl -X POST "https://api.trigger.dev/api/v1/webhooks/deliveries/whd_1234/replay -H "Authorization: Bearer $TRIGGER_SECRET_KEY" ``` -Add `?targetId=` to send it to one subscriber regardless of its filter. `targetId` is the subscriber id: a `webhook()` task's id, or `agentId:eventId` for an agent's `chat.event` or channel. A replay never resumes waiting runs. +Add `?targetId=` to send it to one subscriber regardless of its filter. `targetId` is the subscriber id: a `webhook()` task's id, `agentId:eventId` for an agent's `chat.event`, or `agentId:connectorId` for a channel. A replay never resumes waiting runs. ## From an agent or the API diff --git a/docs/webhooks/filters.mdx b/docs/webhooks/filters.mdx index 504f317db45..000ad3daa02 100644 --- a/docs/webhooks/filters.mdx +++ b/docs/webhooks/filters.mdx @@ -77,7 +77,7 @@ A path reads from one of three namespaces: - `event.*`: the verified, parsed request body, for example `event.data.object.amount`. - `header.*`: an inbound request header, matched case-insensitively, for example `header.x-github-event`. -- `webhook.*`: endpoint and delivery metadata: `source`, `id`, `deliveryId`, `externalRef`, and `tenantId`. The last two depend on the endpoint configuration. +- `webhook.*`: endpoint and delivery metadata: `source`, `id`, `deliveryId`, `externalRef`, and `tenantId`. The last two depend on the endpoint configuration. `deliveryId` is the provider's event ID, or a hash of the request when the provider sends none; it isn't the `whd_` delivery id. Paths must have non-empty segments. `event.data.amount` is valid; `event.`, `event..amount`, and `event.amount.` are rejected. diff --git a/docs/webhooks/providers.mdx b/docs/webhooks/providers.mdx index f8049bb5b9f..940cd527087 100644 --- a/docs/webhooks/providers.mdx +++ b/docs/webhooks/providers.mdx @@ -12,11 +12,11 @@ description: "Every built-in webhook provider, with its SDK function, the creden | [Autumn](/webhooks/providers/autumn) | `webhooks.autumn()` | Issued by the provider | | [Brex](/webhooks/providers/brex) | `webhooks.brex()` | Issued by the provider | | [Cal.com](/webhooks/providers/cal-com) | `webhooks.calCom()` | You generate it, or the provider issues it | -| [Calendly](/webhooks/providers/calendly) | `webhooks.calendly()` | Issued by the provider | +| [Calendly](/webhooks/providers/calendly) | `webhooks.calendly()` | You choose it (OAuth apps: issued by the provider) | | [Clerk](/webhooks/providers/clerk) | `webhooks.clerk()` | Issued by the provider | | [Composio](/webhooks/providers/composio) | `webhooks.composio()` | Issued by the provider | | [Discord](/webhooks/providers/discord) | `webhooks.discord()` | Provider's public key | -| [DocuSign](/webhooks/providers/docusign) | `webhooks.docusign()` | You generate it, or the provider issues it | +| [DocuSign](/webhooks/providers/docusign) | `webhooks.docusign()` | Issued by the provider | | [ElevenLabs](/webhooks/providers/elevenlabs) | `webhooks.elevenlabs()` | Issued by the provider | | [Firecrawl](/webhooks/providers/firecrawl) | `webhooks.firecrawl()` | Issued by the provider | | [GitHub](/webhooks/providers/github) | `webhooks.github()` | You generate it | @@ -39,7 +39,7 @@ description: "Every built-in webhook provider, with its SDK function, the creden | [Recall.ai](/webhooks/providers/recall-ai) | `webhooks.recallai()` | Issued by the provider | | [Replicate](/webhooks/providers/replicate) | `webhooks.replicate()` | Issued by the provider | | [Resend](/webhooks/providers/resend) | `webhooks.resend()` | Issued by the provider | -| [Retell AI](/webhooks/providers/retell) | `webhooks.retell()` | Issued by the provider | +| [Retell AI](/webhooks/providers/retell) | `webhooks.retell()` | Your API key with the webhook badge | | [Sentry](/webhooks/providers/sentry) | `webhooks.sentry()` | You generate it, or the provider issues it | | [Shopify](/webhooks/providers/shopify) | `webhooks.shopify()` | Issued by the provider | | [Slack](/webhooks/providers/slack) | `webhookSource()` (`@trigger.dev/slack`) | Issued by the provider | @@ -48,7 +48,7 @@ description: "Every built-in webhook provider, with its SDK function, the creden | [Supabase](/webhooks/providers/supabase) | `webhooks.supabase()` | You generate it | | [Tailscale](/webhooks/providers/tailscale) | `webhooks.tailscale()` | Issued by the provider | | [Typeform](/webhooks/providers/typeform) | `webhooks.typeform()` | You generate it, or the provider issues it | -| [Vapi](/webhooks/providers/vapi) | `webhooks.vapi()` | You generate it, or the provider issues it | +| [Vapi](/webhooks/providers/vapi) | `webhooks.vapi()` | You generate it | | [Vercel](/webhooks/providers/vercel) | `webhooks.vercel()` | You generate it, or the provider issues it | | [WhatsApp](/webhooks/providers/whatsapp) | `webhooks.whatsapp()` | Issued by the provider | | [WorkOS](/webhooks/providers/workos) | `webhooks.workos()` | Issued by the provider | diff --git a/docs/webhooks/providers/autumn.mdx b/docs/webhooks/providers/autumn.mdx index 04d111794f8..7c87f1757a0 100644 --- a/docs/webhooks/providers/autumn.mdx +++ b/docs/webhooks/providers/autumn.mdx @@ -35,7 +35,6 @@ export const autumnEvents = webhook({ ## Set up Autumn 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Ask Autumn support to turn on webhooks for your account; they are in beta. -3. In the Autumn dashboard's webhook settings, add the webhook URL as an endpoint and select the event types your subscribers need. -4. Copy the endpoint's signing secret (it starts with `whsec_`), then choose **Set signing secret** on the Trigger.dev endpoint. -5. Send a test event from Autumn, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. +2. In the Autumn dashboard, open **Developer** and select the **Webhooks** tab. Choose **Add Endpoint**, enter the webhook URL and select the events your subscribers need. +3. Copy the endpoint's signing secret (it starts with `whsec_`), then choose **Set signing secret** on the Trigger.dev endpoint. +4. Choose **Send Test Event** in Autumn, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/brex.mdx b/docs/webhooks/providers/brex.mdx index 7d92f6c5b08..85f44f48d06 100644 --- a/docs/webhooks/providers/brex.mdx +++ b/docs/webhooks/providers/brex.mdx @@ -29,13 +29,13 @@ To run a subscriber only for some events, add a [filter](/webhooks/filters) on ` | --- | --- | | Source | `webhooks.brex()` | | Verification | Svix (`svix-id`, `svix-timestamp`, `svix-signature`) | -| Credential | Signing secret issued by Brex | +| Credential | Signing secret from `GET /v1/webhooks/secrets` | | Event type | `event.event_type` | | Brex docs | [Brex webhook docs](https://developer.brex.com/guides/webhooks) | ## Set up Brex 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as an endpoint in Brex's webhook settings and subscribe it to the event types your subscribers need. -3. Copy the endpoint's signing secret (it starts with `whsec_`), then choose **Set signing secret** on the Trigger.dev endpoint. +2. Brex has no webhook settings page. Register the webhook URL with `POST /v1/webhooks`, passing `url` and the `event_types` your subscribers need. Brex allows one webhook endpoint per customer. +3. Get the signing secret from `GET /v1/webhooks/secrets`, then choose **Set signing secret** on the Trigger.dev endpoint and paste it. The secret has no `whsec_` prefix. During a key rotation the call returns two secrets; use the new one. 4. Send a test event from Brex, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/calendly.mdx b/docs/webhooks/providers/calendly.mdx index 08f3dcfe8c7..b2527658430 100644 --- a/docs/webhooks/providers/calendly.mdx +++ b/docs/webhooks/providers/calendly.mdx @@ -29,13 +29,13 @@ To run a subscriber only for some events, add a [filter](/webhooks/filters) on ` | --- | --- | | Source | `webhooks.calendly()` | | Verification | HMAC-SHA256 in `calendly-webhook-signature` | -| Credential | Signing secret issued by Calendly | +| Credential | The `signing_key` you set on the subscription | | Event type | `event.event` | | Calendly docs | [Calendly webhook docs](https://developer.calendly.com/api-docs/overview/webhooks/webhook-signatures) | ## Set up Calendly 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as a webhook in Calendly and select the events your subscribers need. See Calendly's [webhook docs](https://developer.calendly.com/api-docs/overview/webhooks/webhook-signatures) for where its webhook settings are. -3. Copy the signing secret Calendly shows for the webhook, then choose **Set signing secret** on the Trigger.dev endpoint. +2. Calendly webhooks are created through the API, on a paid plan. Choose a signing key (for example, the output of `openssl rand -hex 32`), then create the subscription with `POST https://api.calendly.com/webhook_subscriptions`, passing `url` (the webhook URL), `events`, `organization`, `scope` and `signing_key`. If you create the subscription from an OAuth app, Calendly generates the signing key instead. +3. Choose **Set signing secret** on the Trigger.dev endpoint and paste the signing key. 4. Send a test event from Calendly, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/discord.mdx b/docs/webhooks/providers/discord.mdx index 74fc8e762c0..05b8cd4a45b 100644 --- a/docs/webhooks/providers/discord.mdx +++ b/docs/webhooks/providers/discord.mdx @@ -36,8 +36,8 @@ To run a subscriber only for some events, add a [filter](/webhooks/filters) on ` ## Set up Discord 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. In the [Discord Developer Portal](https://discord.com/developers/applications), open the application, then its **Webhooks** page. Set the **Endpoint URL** to the webhook URL, turn **Events** on, and select the event types your subscribers need. -3. Copy the **Public Key** from the application's **General Information** page, then choose **Set public key** on the Trigger.dev endpoint. Discord sends a PING that the endpoint answers once the key is set. +2. In the [Discord Developer Portal](https://discord.com/developers/applications), open the application and copy the **Public Key** from its **General Information** page. Choose **Set public key** on the Trigger.dev endpoint and paste it. +3. Open the application's **Webhooks** page. Set the **Endpoint URL** to the webhook URL, turn **Events** on, and select the event types your subscribers need. Discord sends a PING when you save, and the endpoint can only answer it once the public key is set. 4. Send a test event from Discord, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. ## Endpoint validation diff --git a/docs/webhooks/providers/docusign.mdx b/docs/webhooks/providers/docusign.mdx index 83dffa3cbdf..097ab24ac14 100644 --- a/docs/webhooks/providers/docusign.mdx +++ b/docs/webhooks/providers/docusign.mdx @@ -29,13 +29,13 @@ To run a subscriber only for some events, add a [filter](/webhooks/filters) on ` | --- | --- | | Source | `webhooks.docusign()` | | Verification | HMAC-SHA256 in `x-docusign-signature-1` | -| Credential | Signing secret you generate on Trigger.dev, or one issued by DocuSign | +| Credential | Connect secret key issued by DocuSign | | Event type | `event.event` | | DocuSign docs | [DocuSign webhook docs](https://developers.docusign.com/platform/webhooks/connect/) | ## Set up DocuSign 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as a webhook in DocuSign and select the events your subscribers need. See DocuSign's [webhook docs](https://developers.docusign.com/platform/webhooks/connect/) for where its webhook settings are. -3. If DocuSign shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If DocuSign asks you for a secret, choose **Generate secret** on the endpoint and paste the value into DocuSign. +2. In DocuSign eSignature Admin, open **Connect > Connect Keys** and choose **Add Secret Key**. Copy the key: DocuSign shows it in full only once. Choose **Set signing secret** on the Trigger.dev endpoint and paste it. +3. Add a Connect configuration with the webhook URL, select the events your subscribers need, and tick **Include HMAC Signature**. Without it, DocuSign doesn't sign deliveries and every one is rejected. 4. Send a test event from DocuSign, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/recall-ai.mdx b/docs/webhooks/providers/recall-ai.mdx index 5b662e1c0e9..a19bec0d832 100644 --- a/docs/webhooks/providers/recall-ai.mdx +++ b/docs/webhooks/providers/recall-ai.mdx @@ -29,13 +29,26 @@ To run a subscriber only for some events, add a [filter](/webhooks/filters) on ` | --- | --- | | Source | `webhooks.recallai()` | | Verification | Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`) | -| Credential | Signing secret issued by Recall.ai | +| Credential | Workspace verification secret issued by Recall.ai | | Event type | `event.event` | | Recall.ai docs | [Recall.ai webhook docs](https://docs.recall.ai/docs/authenticating-requests-from-recallai) | ## Set up Recall.ai 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as an endpoint in Recall.ai's webhook settings and subscribe it to the event types your subscribers need. -3. Copy the endpoint's signing secret (it starts with `whsec_`), then choose **Set signing secret** on the Trigger.dev endpoint. +2. Add the webhook URL as an endpoint on Recall.ai's webhooks dashboard and subscribe it to the event types your subscribers need. +3. Create a workspace verification secret under **Developers > API Keys & Secrets > Create Workspace Secret**, then choose **Set signing secret** on the Trigger.dev endpoint and paste it. Recall.ai sends no signature headers until a workspace secret exists. 4. Send a test event from Recall.ai, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. + +## Accounts created before 15 December 2025 + +Older Recall.ai accounts sign webhooks-dashboard deliveries with `svix-*` headers and a separate secret for each endpoint. For those accounts, declare the endpoint with `webhooks.svix()` instead, and set the endpoint's signing secret from the Recall.ai webhooks dashboard: + +```ts /trigger/recall.ts +import { webhooks } from "@trigger.dev/sdk"; + +export const recall = webhooks.endpoint.define({ + id: "recall", + source: webhooks.svix(), +}); +``` diff --git a/docs/webhooks/providers/replicate.mdx b/docs/webhooks/providers/replicate.mdx index 5fcf0a5dc86..f5d1693f8e9 100644 --- a/docs/webhooks/providers/replicate.mdx +++ b/docs/webhooks/providers/replicate.mdx @@ -36,6 +36,6 @@ To run a subscriber only for some events, add a [filter](/webhooks/filters) on ` ## Set up Replicate 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as an endpoint in Replicate's webhook settings and subscribe it to the event types your subscribers need. -3. Copy the endpoint's signing secret (it starts with `whsec_`), then choose **Set signing secret** on the Trigger.dev endpoint. -4. Send a test event from Replicate, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. +2. Replicate has no webhook settings page. Pass the webhook URL as `webhook` when you create a prediction, with `webhook_events_filter` set to the events you want (`start`, `output`, `logs`, `completed`). +3. Get your signing secret from `GET https://api.replicate.com/v1/webhooks/default/secret`. It starts with `whsec_` and is the same for every webhook on your user or organization. Choose **Set signing secret** on the Trigger.dev endpoint and paste it. +4. Create a prediction with the webhook set, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/retell.mdx b/docs/webhooks/providers/retell.mdx index 6ed91d2c919..8f892153381 100644 --- a/docs/webhooks/providers/retell.mdx +++ b/docs/webhooks/providers/retell.mdx @@ -29,13 +29,13 @@ To run a subscriber only for some events, add a [filter](/webhooks/filters) on ` | --- | --- | | Source | `webhooks.retell()` | | Verification | HMAC-SHA256 in `x-retell-signature` | -| Credential | Signing secret issued by Retell AI | +| Credential | The Retell AI API key with the webhook badge | | Event type | `event.event` | | Retell AI docs | [Retell AI webhook docs](https://docs.retellai.com/features/secure-webhook) | ## Set up Retell AI 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as a webhook in Retell AI and select the events your subscribers need. See Retell AI's [webhook docs](https://docs.retellai.com/features/secure-webhook) for where its webhook settings are. -3. Copy the signing secret Retell AI shows for the webhook, then choose **Set signing secret** on the Trigger.dev endpoint. +2. In Retell AI, set the webhook URL as the account-level webhook in the system settings' **Webhooks** tab, or as an agent's **Agent Level Webhook URL** under **Webhook settings** in the agent editor. An agent-level URL replaces the account-level one for that agent. +3. Retell AI signs with an API key, not a per-webhook secret. Copy the API key that has the webhook badge next to it, then choose **Set signing secret** on the Trigger.dev endpoint and paste it. 4. Send a test event from Retell AI, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/slack.mdx b/docs/webhooks/providers/slack.mdx index 9909d66a1cd..b545d7fd36d 100644 --- a/docs/webhooks/providers/slack.mdx +++ b/docs/webhooks/providers/slack.mdx @@ -39,7 +39,7 @@ To run a subscriber only for some events, add a [filter](/webhooks/filters) on ` 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. 2. In your Slack app's settings, set the **Event Subscriptions** request URL to the webhook URL and subscribe to the bot events your subscribers need. 3. Copy the app's **Signing Secret** from **Basic Information > App Credentials**, then choose **Set signing secret** on the Trigger.dev endpoint. -4. Back on the Event Subscriptions page, choose **Verify**. Slack's `url_verification` challenge is answered by the endpoint once the secret is set. +4. Back on the Event Subscriptions page, choose **Retry**. Slack's `url_verification` challenge is answered by the endpoint once the secret is set. 5. Send a test event from Slack, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. ## Build a Slack agent diff --git a/docs/webhooks/providers/vapi.mdx b/docs/webhooks/providers/vapi.mdx index f32cf21dbf0..5b9f1a3070b 100644 --- a/docs/webhooks/providers/vapi.mdx +++ b/docs/webhooks/providers/vapi.mdx @@ -29,13 +29,19 @@ To run a subscriber only for some events, add a [filter](/webhooks/filters) on ` | --- | --- | | Source | `webhooks.vapi()` | | Verification | HMAC-SHA256 in `x-vapi-signature` | -| Credential | Signing secret you generate on Trigger.dev, or one issued by Vapi | +| Credential | Secret you generate on Trigger.dev and add to a Vapi HMAC credential | | Event type | `event.message.type` | | Vapi docs | [Vapi webhook docs](https://docs.vapi.ai/server-url/server-authentication) | ## Set up Vapi 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as a webhook in Vapi and select the events your subscribers need. See Vapi's [webhook docs](https://docs.vapi.ai/server-url/server-authentication) for where its webhook settings are. -3. If Vapi shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Vapi asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Vapi. -4. Send a test event from Vapi, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. +2. Choose **Generate secret** on the Trigger.dev endpoint and copy the value. +3. In the Vapi Dashboard, open **Integrations > Server Configuration** and choose **Add Custom Credential**. Choose **HMAC** and set: + - **Secret Key**: the secret you generated + - **Algorithm**: SHA256 + - **Signature Header**: `x-vapi-signature` + - **Timestamp Header**: leave empty + - **Payload Format**: the request body only, with no timestamp +4. Set the webhook URL as the server URL on your assistant, phone number or Server Configuration, and attach the credential by its `credentialId`. Vapi only sends the credential when the server URL comes from your saved configuration, not from an API request. +5. Send a test event from Vapi, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/session-routing.mdx b/docs/webhooks/session-routing.mdx index 297e63bd85c..a3cf587cb25 100644 --- a/docs/webhooks/session-routing.mdx +++ b/docs/webhooks/session-routing.mdx @@ -36,7 +36,7 @@ The endpoint's other subscribers, such as a `webhook()` task, still get the same The `key` is what makes routing durable: two deliveries that resolve to the same key reach the same session; a different key gets its own. It is a template string, evaluated server-side at ingest, whose `{...}` placeholders read three namespaces: - `{event.*}`: the parsed event body. -- `{webhook.*}`: endpoint metadata (`externalRef`, `tenantId`, `id`, `source`, `deliveryId`). +- `{webhook.*}`: endpoint metadata (`externalRef`, `tenantId`, `id`, `source`, `deliveryId`). Here `deliveryId` is the provider's event ID, not the `whd_` id. - `{header.name}`: an inbound header. These are the same namespaces [filter](/webhooks/filters) expressions use. Every placeholder names one: a bare `{customer}` is an error. diff --git a/docs/webhooks/waiters.mdx b/docs/webhooks/waiters.mdx index 17552272d4a..df6829be36f 100644 --- a/docs/webhooks/waiters.mdx +++ b/docs/webhooks/waiters.mdx @@ -67,7 +67,7 @@ Match on values you control, such as your own order id in the provider object's | --- | --- | | `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`. | +| `webhook.*` | The endpoint: `id`, `source`, `externalRef`, `tenantId`, or `deliveryId` (the provider's event ID, or a hash of the request when the provider sends none; not the `whd_` id). | 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. @@ -96,7 +96,7 @@ if (result.ok) { | Output field | Value | | --- | --- | | `event` | The verified event body, typed by the endpoint's source. | -| `headers` | The request headers, with credentials such as signatures removed. | +| `headers` | The request headers, without `authorization`, cookie or shared-secret headers. Headers your `match` uses are always kept; the rest are capped at 4 KB. | | `deliveryId` | The delivery that resumed the run (`whd_...`). | | `endpoint` | The endpoint the delivery arrived on. | diff --git a/docs/webhooks/webhook-tasks.mdx b/docs/webhooks/webhook-tasks.mdx index 8f4063e1249..95062ef0540 100644 --- a/docs/webhooks/webhook-tasks.mdx +++ b/docs/webhooks/webhook-tasks.mdx @@ -13,7 +13,7 @@ description: "What a webhook() handler receives, the task options it takes, how | Argument | Value | | --- | --- | | `event` | The verified request body, parsed as JSON. Its TypeScript type comes from the [source](/webhooks/verification#typing-the-event). | -| `headers` | Request headers as a Web `Headers` object, with case-insensitive `get()` and `has()` methods. Credentials such as signatures are removed. | +| `headers` | Request headers as a Web `Headers` object, with case-insensitive `get()` and `has()` methods. `authorization`, `proxy-authorization`, `cookie`, `set-cookie` and shared-secret headers are removed; signature headers such as `stripe-signature` are kept. Stored headers are capped at 4 KB. | | `endpoint` | The endpoint the delivery arrived on: `id`, `declaredId`, `tenantId`, `externalRef`, and the `metadata` you declared. | | `ctx` | The same [run context](/context) that regular tasks receive. | From 740c9731fc548527cb48ca52f6cfd36972f71f07 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 15:37:11 +0000 Subject: [PATCH 27/37] docs: remove the Zoom webhook provider page webhooks.zoom() isn't exported by the SDK yet, so drop the page, its providers table row and sidebar entry, and redirect the URL to the providers list. --- docs/docs.json | 7 ++++-- docs/webhooks/providers.mdx | 1 - docs/webhooks/providers/zoom.mdx | 41 -------------------------------- 3 files changed, 5 insertions(+), 44 deletions(-) delete mode 100644 docs/webhooks/providers/zoom.mdx diff --git a/docs/docs.json b/docs/docs.json index 836f60d616d..e73c29e354c 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -235,8 +235,7 @@ "webhooks/providers/vercel", "webhooks/providers/whatsapp", "webhooks/providers/workos", - "webhooks/providers/zendesk", - "webhooks/providers/zoom" + "webhooks/providers/zendesk" ] }, "webhooks/custom-providers", @@ -901,6 +900,10 @@ "source": "/guides/examples/hookdeck-webhook", "destination": "/webhooks/providers/hookdeck" }, + { + "source": "/webhooks/providers/zoom", + "destination": "/webhooks/providers" + }, { "source": "/examples/stripe-webhook", "destination": "/webhooks/providers/stripe" diff --git a/docs/webhooks/providers.mdx b/docs/webhooks/providers.mdx index 940cd527087..e5f846a8aa6 100644 --- a/docs/webhooks/providers.mdx +++ b/docs/webhooks/providers.mdx @@ -53,6 +53,5 @@ description: "Every built-in webhook provider, with its SDK function, the creden | [WhatsApp](/webhooks/providers/whatsapp) | `webhooks.whatsapp()` | Issued by the provider | | [WorkOS](/webhooks/providers/workos) | `webhooks.workos()` | Issued by the provider | | [Zendesk](/webhooks/providers/zendesk) | `webhooks.zendesk()` | You generate it, or the provider issues it | -| [Zoom](/webhooks/providers/zoom) | `webhooks.zoom()` | Issued by the provider | For a provider that isn't listed, define a [custom provider](/webhooks/custom-providers). For providers that sign with Svix or Standard Webhooks, `webhooks.svix()` and `webhooks.standardWebhooks()` also work; see [Verification](/webhooks/verification#svix-and-standard-webhooks). diff --git a/docs/webhooks/providers/zoom.mdx b/docs/webhooks/providers/zoom.mdx deleted file mode 100644 index 0e28924c367..00000000000 --- a/docs/webhooks/providers/zoom.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: "Zoom webhooks" -sidebarTitle: "Zoom" -description: "Receive Zoom webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Zoom, and how to set the signing credential." ---- - -**`webhooks.zoom()` verifies Zoom's signature on every request, so subscribers only receive genuine Zoom events.** - -```ts /trigger/zoom.ts -import { webhook, webhooks } from "@trigger.dev/sdk"; - -export const zoom = webhooks.endpoint.define({ - id: "zoom", - source: webhooks.zoom(), -}); - -export const zoomEvents = webhook({ - id: "zoom-events", - endpoint: zoom, - onEvent: async ({ event }) => { - console.log(event); - }, -}); -``` - -To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event`. - -| | | -| --- | --- | -| Source | `webhooks.zoom()` | -| Verification | HMAC-SHA256 in `x-zm-signature` | -| Credential | Signing secret issued by Zoom | -| Event type | `event.event` | -| Zoom docs | [Zoom webhook docs](https://developers.zoom.us/docs/api/webhooks/) | - -## Set up Zoom - -1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as a webhook in Zoom and select the events your subscribers need. See Zoom's [webhook docs](https://developers.zoom.us/docs/api/webhooks/) for where its webhook settings are. -3. Copy the signing secret Zoom shows for the webhook, then choose **Set signing secret** on the Trigger.dev endpoint. -4. Send a test event from Zoom, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. From 02d1328fae58c5271d69bea528e4c424c061769d Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 16:00:07 +0000 Subject: [PATCH 28/37] docs: document additionalSignatureHeaders and merge duplicate test steps Carry the additionalSignatureHeaders option for custom HMAC providers over from the removed sources page, and merge the two overlapping test steps on the Loops, Tailscale and PlanetScale pages. --- docs/webhooks/custom-providers.mdx | 2 ++ docs/webhooks/providers/loops.mdx | 3 +-- docs/webhooks/providers/planetscale.mdx | 3 +-- docs/webhooks/providers/tailscale.mdx | 3 +-- 4 files changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/webhooks/custom-providers.mdx b/docs/webhooks/custom-providers.mdx index f3c3bb76e64..ea50d8df6f3 100644 --- a/docs/webhooks/custom-providers.mdx +++ b/docs/webhooks/custom-providers.mdx @@ -37,6 +37,8 @@ export const internalEvents = webhook({ }); ``` +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. + 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 diff --git a/docs/webhooks/providers/loops.mdx b/docs/webhooks/providers/loops.mdx index 74b52877f4b..090bea5c131 100644 --- a/docs/webhooks/providers/loops.mdx +++ b/docs/webhooks/providers/loops.mdx @@ -37,5 +37,4 @@ export const loopsEvents = webhook({ 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. 2. In Loops, go to **Settings > Webhooks**, add the webhook URL as the endpoint, and select the events your subscribers need. 3. Copy the endpoint's signing secret (it starts with `whsec_`), then choose **Set signing secret** on the Trigger.dev endpoint. -4. Send a `testing.testEvent` from the Loops settings page to confirm delivery. -5. Send a test event from Loops, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. +4. Send a `testing.testEvent` from the Loops settings page, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/planetscale.mdx b/docs/webhooks/providers/planetscale.mdx index a9feb6a9076..c0984d00a6f 100644 --- a/docs/webhooks/providers/planetscale.mdx +++ b/docs/webhooks/providers/planetscale.mdx @@ -37,5 +37,4 @@ export const planetscaleEvents = webhook({ 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. 2. Select the database in PlanetScale, then **Settings > Webhooks > Add webhook**. Enter the webhook URL and select the events your subscribers need. This needs the database administrator role. 3. In the webhook's menu, choose **Show secret**, copy it, and choose **Set signing secret** on the Trigger.dev endpoint. -4. Choose **Test webhook** in the same menu to send a `webhook.test` event. -5. Send a test event from PlanetScale, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. +4. Choose **Test webhook** in the same menu to send a `webhook.test` event, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/tailscale.mdx b/docs/webhooks/providers/tailscale.mdx index c2e57c45541..02ee1d87881 100644 --- a/docs/webhooks/providers/tailscale.mdx +++ b/docs/webhooks/providers/tailscale.mdx @@ -36,8 +36,7 @@ export const tailscaleEvents = webhook({ 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. 2. On the **Webhooks** page of the Tailscale admin console, select **Add endpoint**, enter the webhook URL, and choose the events your subscribers need. This needs the Owner, Admin, Network admin or IT admin role. 3. Tailscale shows the webhook secret once, right after the endpoint is added. Copy it then, and choose **Set signing secret** on the Trigger.dev endpoint. -4. Use the endpoint's menu, **Test endpoint > Send test event**, to confirm delivery. -5. Send a test event from Tailscale, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. +4. Use the Tailscale endpoint's menu, **Test endpoint > Send test event**, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. ## Batched events From 4d38aecbb19a12140ba7bdb060fd8862e28954bd Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 16:01:17 +0000 Subject: [PATCH 29/37] docs: make webhook provider pages specific and tighten channel docs Give each provider page its own description and opener naming the signature it checks, label the settings table, and remove filler wording from the channels, session routing, Slack, Linear and channel human-in-the-loop pages. --- docs/webhooks/channels.mdx | 8 ++++---- docs/webhooks/human-in-the-loop.mdx | 2 +- docs/webhooks/linear.mdx | 4 ++-- docs/webhooks/providers/attio.mdx | 6 +++--- docs/webhooks/providers/autumn.mdx | 6 +++--- docs/webhooks/providers/brex.mdx | 6 +++--- docs/webhooks/providers/cal-com.mdx | 6 +++--- docs/webhooks/providers/calendly.mdx | 6 +++--- docs/webhooks/providers/clerk.mdx | 6 +++--- docs/webhooks/providers/composio.mdx | 6 +++--- docs/webhooks/providers/discord.mdx | 6 +++--- docs/webhooks/providers/docusign.mdx | 6 +++--- docs/webhooks/providers/elevenlabs.mdx | 6 +++--- docs/webhooks/providers/firecrawl.mdx | 6 +++--- docs/webhooks/providers/github.mdx | 6 +++--- docs/webhooks/providers/gitlab.mdx | 6 +++--- docs/webhooks/providers/granola.mdx | 6 +++--- docs/webhooks/providers/hookdeck.mdx | 6 +++--- docs/webhooks/providers/infisical.mdx | 6 +++--- docs/webhooks/providers/intercom.mdx | 6 +++--- docs/webhooks/providers/jira.mdx | 6 +++--- docs/webhooks/providers/langfuse.mdx | 6 +++--- docs/webhooks/providers/linear.mdx | 6 +++--- docs/webhooks/providers/loops.mdx | 6 +++--- docs/webhooks/providers/metronome.mdx | 6 +++--- docs/webhooks/providers/mux.mdx | 6 +++--- docs/webhooks/providers/notion.mdx | 6 +++--- docs/webhooks/providers/openai.mdx | 6 +++--- docs/webhooks/providers/pagerduty.mdx | 6 +++--- docs/webhooks/providers/plain.mdx | 6 +++--- docs/webhooks/providers/planetscale.mdx | 6 +++--- docs/webhooks/providers/recall-ai.mdx | 6 +++--- docs/webhooks/providers/replicate.mdx | 6 +++--- docs/webhooks/providers/resend.mdx | 6 +++--- docs/webhooks/providers/retell.mdx | 6 +++--- docs/webhooks/providers/sentry.mdx | 6 +++--- docs/webhooks/providers/shopify.mdx | 6 +++--- docs/webhooks/providers/slack.mdx | 6 +++--- docs/webhooks/providers/square.mdx | 6 +++--- docs/webhooks/providers/stripe.mdx | 4 ++-- docs/webhooks/providers/supabase.mdx | 4 ++-- docs/webhooks/providers/tailscale.mdx | 6 +++--- docs/webhooks/providers/typeform.mdx | 6 +++--- docs/webhooks/providers/vapi.mdx | 6 +++--- docs/webhooks/providers/vercel.mdx | 6 +++--- docs/webhooks/providers/whatsapp.mdx | 6 +++--- docs/webhooks/providers/workos.mdx | 6 +++--- docs/webhooks/providers/zendesk.mdx | 6 +++--- docs/webhooks/session-routing.mdx | 8 ++++---- docs/webhooks/slack.mdx | 2 +- 50 files changed, 145 insertions(+), 145 deletions(-) diff --git a/docs/webhooks/channels.mdx b/docs/webhooks/channels.mdx index 1b48b899d90..cc9477ea217 100644 --- a/docs/webhooks/channels.mdx +++ b/docs/webhooks/channels.mdx @@ -4,7 +4,7 @@ description: "Point Slack (or any chat surface) at an agent: messages become tur sidebarTitle: "Overview" --- -A [session route](/webhooks/session-routing) delivers a verified event to an agent as an [action](/ai-chat/actions): the agent reacts, and the response is a side effect. A **channel** is the other half: the webhook IS the chat surface. Inbound messages become **turns** (the normal `run()` loop), and the agent's reply is posted **back** to the surface. A Slack thread becomes a real conversation with the agent, exactly like the browser chat, just a different frontend. +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. List channels on a [`chat.agent`](/ai-chat/overview) alongside (or instead of) `events`: @@ -31,7 +31,7 @@ export const supportAgent = chat.agent({ }); ``` -The `run()` loop is unchanged: the agent does not know or care that it is talking to Slack. One verified Slack message in a thread is routed to a durable [session](/ai-chat/sessions) keyed to that thread, run as a turn, and the reply is posted into the thread. +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. ## Slack @@ -98,7 +98,7 @@ slack({ ## Stopping a turn from the channel -A connector can map an event to a control with `onControl`. Returning `{ kind: "stop" }` while a turn is running aborts it through the run's `stopSignal`, exactly like the browser's stop button: the partial reply posts with `stopped: true` and the event is consumed instead of running as a turn. `linear()` and `slack()` map their stop buttons this way; a custom connector might map a `/stop` command: +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: ```ts chat.channels.custom({ @@ -139,7 +139,7 @@ chat.channels.custom({ ## Files, buttons and steering -Three more hooks cover what a chat surface carries besides text: +These hooks cover what a chat surface carries besides text: - `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. - `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. diff --git a/docs/webhooks/human-in-the-loop.mdx b/docs/webhooks/human-in-the-loop.mdx index c28066c452b..eb9b8279230 100644 --- a/docs/webhooks/human-in-the-loop.mdx +++ b/docs/webhooks/human-in-the-loop.mdx @@ -4,7 +4,7 @@ sidebarTitle: "Human-in-the-loop" description: "Pause an agent mid-turn to get a human decision from the channel (Slack approve/deny), then resume with the answer." --- -**An agent on a [channel](/webhooks/channels) can pause a turn to get a human decision, then resume once someone answers in the thread.** It posts controls into the conversation and picks up where it left off once someone clicks, with the decision merged into the turn. The click arrives as a webhook on the same endpoint as the conversation's messages, and that delivery resumes the paused run. To pause a run until any other webhook arrives, use a [waiter](/webhooks/waiters). This is the channel counterpart of browser [human-in-the-loop](/ai-chat/patterns/human-in-the-loop): the same no-`execute` tool, but the controls live in Slack (or your own surface) instead of a React component. The [`slack()`](/webhooks/slack) connector ships Approve and Deny buttons out of the box. +**An agent on a [channel](/webhooks/channels) can pause a turn to get a human decision, then resume once someone answers in the thread.** It posts controls into the conversation and picks up where it left off once someone clicks, with the decision merged into the turn. The click arrives as a webhook on the same endpoint as the conversation's messages, and that delivery resumes the paused run. To pause a run until any other webhook arrives, use a [waiter](/webhooks/waiters). This is the channel counterpart of browser [human-in-the-loop](/ai-chat/patterns/human-in-the-loop): the same no-`execute` tool, but the controls live in Slack (or your own surface) instead of a React component. The [`slack()`](/webhooks/slack) connector includes Approve and Deny buttons. ## How it works diff --git a/docs/webhooks/linear.mdx b/docs/webhooks/linear.mdx index 239a99cf814..9ea927b8837 100644 --- a/docs/webhooks/linear.mdx +++ b/docs/webhooks/linear.mdx @@ -48,7 +48,7 @@ The `run()` loop is the same one a browser chat or a Slack thread uses. Verifica On the first turn of a session the connector frames Linear's payload for the model: who summoned it and on which issue, the workspace **guidance** rules for agents, Linear's formatted **issue context** (title, description, labels, project, comments), and the comment that mentioned it. An assignment with no comment reads as "assigned ENG-412 to you". Prior comments on the issue are seeded as transcript messages, so the agent can answer with the context a reader of the issue has. -A follow-up prompt on the session is just the message. If the user hits **Stop** in Linear, see [Stopping](#stopping). +A follow-up prompt on the session is the message itself. If the user hits **Stop** in Linear, see [Stopping](#stopping). Images and PDFs uploaded to Linear reach the model as files: screenshots in the prompt, in the comment that mentioned the agent, or in the issue description. The transcript keeps the upload link, and the `streamText` passed to `run()` downloads the file with the app's token when the model reads it, at most ten per message. A file that can't be downloaded reaches the model as a short note. A custom `inbound` keeps this by adding `linearFileParts(markdown)` to its message parts. @@ -109,7 +109,7 @@ For manual control, `chat.surface()` returns the current turn' ## Approvals and choices -A tool with no `execute` pauses the turn for a human decision, exactly as on [any channel](/webhooks/human-in-the-loop). On Linear the connector posts an elicitation card with Approve and Deny options. The card lays the tool input out as markdown: a list of proposed items becomes a numbered list with a bold title per item, a flat object becomes key and value bullets, and only shapes it cannot lay out fall back to JSON. For a card written for the tool, pass a renderer per tool name: +A tool with no `execute` pauses the turn for a human decision, as on [any channel](/webhooks/human-in-the-loop). On Linear the connector posts an elicitation card with Approve and Deny options. The card lays the tool input out as markdown: a list of proposed items becomes a numbered list with a bold title per item, a flat object becomes key and value bullets, and only shapes it cannot lay out fall back to JSON. For a card written for the tool, pass a renderer per tool name: ```ts linear({ diff --git a/docs/webhooks/providers/attio.mdx b/docs/webhooks/providers/attio.mdx index e60bea6e84d..220fda2c0b3 100644 --- a/docs/webhooks/providers/attio.mdx +++ b/docs/webhooks/providers/attio.mdx @@ -1,10 +1,10 @@ --- title: "Attio webhooks" sidebarTitle: "Attio" -description: "Receive Attio webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Attio, and how to set the signing credential." +description: "Receive and verify Attio webhooks with Trigger.dev. Check the HMAC-SHA256 signature in attio-signature and run a task for each Attio event." --- -**`webhooks.attio()` verifies Attio's signature on every request, so subscribers only receive genuine Attio events.** +**`webhooks.attio()` verifies the HMAC-SHA256 signature Attio sends in `attio-signature` on every request.** ```ts /trigger/attio.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -23,7 +23,7 @@ export const attioEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.attio()` | | Verification | HMAC-SHA256 in `attio-signature` | diff --git a/docs/webhooks/providers/autumn.mdx b/docs/webhooks/providers/autumn.mdx index 7c87f1757a0..8da436c0371 100644 --- a/docs/webhooks/providers/autumn.mdx +++ b/docs/webhooks/providers/autumn.mdx @@ -1,10 +1,10 @@ --- title: "Autumn webhooks" sidebarTitle: "Autumn" -description: "Receive Autumn webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Autumn, and how to set the signing credential." +description: "Receive and verify Autumn webhooks with Trigger.dev. Check the Svix signature and run a task for each Autumn event, filtered on event.type." --- -**`webhooks.autumn()` verifies Autumn's signature on every request, so subscribers only receive genuine Autumn events.** +**`webhooks.autumn()` verifies the Svix signature Autumn sends in the `svix-*` headers on every request.** ```ts /trigger/autumn.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -24,7 +24,7 @@ export const autumnEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.autumn()` | | Verification | Svix (`svix-id`, `svix-timestamp`, `svix-signature`) | diff --git a/docs/webhooks/providers/brex.mdx b/docs/webhooks/providers/brex.mdx index 85f44f48d06..ca6de1ffc8a 100644 --- a/docs/webhooks/providers/brex.mdx +++ b/docs/webhooks/providers/brex.mdx @@ -1,10 +1,10 @@ --- title: "Brex webhooks" sidebarTitle: "Brex" -description: "Receive Brex webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Brex, and how to set the signing credential." +description: "Receive and verify Brex webhooks with Trigger.dev. Check the Svix signature and run a task for each Brex event, filtered on event.event_type." --- -**`webhooks.brex()` verifies Brex's signature on every request, so subscribers only receive genuine Brex events.** +**`webhooks.brex()` verifies the Svix signature Brex sends in the `svix-*` headers on every request.** ```ts /trigger/brex.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -25,7 +25,7 @@ export const brexEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event_type`. -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.brex()` | | Verification | Svix (`svix-id`, `svix-timestamp`, `svix-signature`) | diff --git a/docs/webhooks/providers/cal-com.mdx b/docs/webhooks/providers/cal-com.mdx index 9327dba4660..041a8a1ac2d 100644 --- a/docs/webhooks/providers/cal-com.mdx +++ b/docs/webhooks/providers/cal-com.mdx @@ -1,10 +1,10 @@ --- title: "Cal.com webhooks" sidebarTitle: "Cal.com" -description: "Receive Cal.com webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Cal.com, and how to set the signing credential." +description: "Receive and verify Cal.com webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-cal-signature-256 and run a task for each Cal.com event, filtered on event.triggerEvent." --- -**`webhooks.calCom()` verifies Cal.com's signature on every request, so subscribers only receive genuine Cal.com events.** +**`webhooks.calCom()` verifies the HMAC-SHA256 signature Cal.com sends in `x-cal-signature-256` on every request.** ```ts /trigger/cal-com.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -25,7 +25,7 @@ export const calComEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.triggerEvent`. -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.calCom()` | | Verification | HMAC-SHA256 in `x-cal-signature-256` | diff --git a/docs/webhooks/providers/calendly.mdx b/docs/webhooks/providers/calendly.mdx index b2527658430..0a41022a05f 100644 --- a/docs/webhooks/providers/calendly.mdx +++ b/docs/webhooks/providers/calendly.mdx @@ -1,10 +1,10 @@ --- title: "Calendly webhooks" sidebarTitle: "Calendly" -description: "Receive Calendly webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Calendly, and how to set the signing credential." +description: "Receive and verify Calendly webhooks with Trigger.dev. Check the HMAC-SHA256 signature in calendly-webhook-signature and run a task for each Calendly event, filtered on event.event." --- -**`webhooks.calendly()` verifies Calendly's signature on every request, so subscribers only receive genuine Calendly events.** +**`webhooks.calendly()` verifies the HMAC-SHA256 signature Calendly sends in `calendly-webhook-signature` on every request.** ```ts /trigger/calendly.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -25,7 +25,7 @@ export const calendlyEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event`. -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.calendly()` | | Verification | HMAC-SHA256 in `calendly-webhook-signature` | diff --git a/docs/webhooks/providers/clerk.mdx b/docs/webhooks/providers/clerk.mdx index 473eed4df7e..0d635731d6f 100644 --- a/docs/webhooks/providers/clerk.mdx +++ b/docs/webhooks/providers/clerk.mdx @@ -1,10 +1,10 @@ --- title: "Clerk webhooks" sidebarTitle: "Clerk" -description: "Receive Clerk webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Clerk, and how to set the signing credential." +description: "Receive and verify Clerk webhooks with Trigger.dev. Check the Svix signature and run a task for each Clerk event, filtered on event.type." --- -**`webhooks.clerk()` verifies Clerk's signature on every request, so subscribers only receive genuine Clerk events.** +**`webhooks.clerk()` verifies the Svix signature Clerk sends in the `svix-*` headers on every request.** ```ts /trigger/clerk.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -24,7 +24,7 @@ export const clerkEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.clerk()` | | Verification | Svix (`svix-id`, `svix-timestamp`, `svix-signature`) | diff --git a/docs/webhooks/providers/composio.mdx b/docs/webhooks/providers/composio.mdx index fcb17ff36dd..1da456d8864 100644 --- a/docs/webhooks/providers/composio.mdx +++ b/docs/webhooks/providers/composio.mdx @@ -1,10 +1,10 @@ --- title: "Composio webhooks" sidebarTitle: "Composio" -description: "Receive Composio webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Composio, and how to set the signing credential." +description: "Receive and verify Composio webhooks with Trigger.dev. Check the Standard Webhooks signature and run a task for each Composio event, filtered on event.type." --- -**`webhooks.composio()` verifies Composio's signature on every request, so subscribers only receive genuine Composio events.** +**`webhooks.composio()` verifies the Standard Webhooks signature Composio sends in the `webhook-*` headers on every request.** ```ts /trigger/composio.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -25,7 +25,7 @@ export const composioEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.type`. -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.composio()` | | Verification | Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`) | diff --git a/docs/webhooks/providers/discord.mdx b/docs/webhooks/providers/discord.mdx index 05b8cd4a45b..dd9b1836aec 100644 --- a/docs/webhooks/providers/discord.mdx +++ b/docs/webhooks/providers/discord.mdx @@ -1,10 +1,10 @@ --- title: "Discord webhooks" sidebarTitle: "Discord" -description: "Receive Discord webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Discord, and how to set the signing credential." +description: "Receive and verify Discord webhooks with Trigger.dev. Check the Ed25519 signature in x-signature-ed25519 and run a task for each Discord event, filtered on event.event.type." --- -**`webhooks.discord()` verifies Discord's signature on every request, so subscribers only receive genuine Discord events.** +**`webhooks.discord()` verifies the Ed25519 signature Discord sends in `x-signature-ed25519` on every request.** ```ts /trigger/discord.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -25,7 +25,7 @@ export const discordEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event.type`. -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.discord()` | | Verification | Ed25519 signature in `x-signature-ed25519` | diff --git a/docs/webhooks/providers/docusign.mdx b/docs/webhooks/providers/docusign.mdx index 097ab24ac14..6de05994707 100644 --- a/docs/webhooks/providers/docusign.mdx +++ b/docs/webhooks/providers/docusign.mdx @@ -1,10 +1,10 @@ --- title: "DocuSign webhooks" sidebarTitle: "DocuSign" -description: "Receive DocuSign webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in DocuSign, and how to set the signing credential." +description: "Receive and verify DocuSign webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-docusign-signature-1 and run a task for each DocuSign event, filtered on event.event." --- -**`webhooks.docusign()` verifies DocuSign's signature on every request, so subscribers only receive genuine DocuSign events.** +**`webhooks.docusign()` verifies the HMAC-SHA256 signature DocuSign sends in `x-docusign-signature-1` on every request.** ```ts /trigger/docusign.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -25,7 +25,7 @@ export const docusignEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event`. -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.docusign()` | | Verification | HMAC-SHA256 in `x-docusign-signature-1` | diff --git a/docs/webhooks/providers/elevenlabs.mdx b/docs/webhooks/providers/elevenlabs.mdx index 842fca4b24f..ea9a3be9e23 100644 --- a/docs/webhooks/providers/elevenlabs.mdx +++ b/docs/webhooks/providers/elevenlabs.mdx @@ -1,10 +1,10 @@ --- title: "ElevenLabs webhooks" sidebarTitle: "ElevenLabs" -description: "Receive ElevenLabs webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in ElevenLabs, and how to set the signing credential." +description: "Receive and verify ElevenLabs webhooks with Trigger.dev. Check the HMAC-SHA256 signature in elevenlabs-signature and run a task for each ElevenLabs event, filtered on event.type." --- -**`webhooks.elevenlabs()` verifies ElevenLabs's signature on every request, so subscribers only receive genuine ElevenLabs events.** +**`webhooks.elevenlabs()` verifies the HMAC-SHA256 signature ElevenLabs sends in `elevenlabs-signature` on every request.** ```ts /trigger/elevenlabs.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -25,7 +25,7 @@ export const elevenlabsEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.type`. -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.elevenlabs()` | | Verification | HMAC-SHA256 in `elevenlabs-signature` | diff --git a/docs/webhooks/providers/firecrawl.mdx b/docs/webhooks/providers/firecrawl.mdx index 53be82383c7..da987c28f45 100644 --- a/docs/webhooks/providers/firecrawl.mdx +++ b/docs/webhooks/providers/firecrawl.mdx @@ -1,10 +1,10 @@ --- title: "Firecrawl webhooks" sidebarTitle: "Firecrawl" -description: "Receive Firecrawl webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Firecrawl, and how to set the signing credential." +description: "Receive and verify Firecrawl webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-firecrawl-signature and run a task for each Firecrawl event, filtered on event.type." --- -**`webhooks.firecrawl()` verifies Firecrawl's signature on every request, so subscribers only receive genuine Firecrawl events.** +**`webhooks.firecrawl()` verifies the HMAC-SHA256 signature Firecrawl sends in `x-firecrawl-signature` on every request.** ```ts /trigger/firecrawl.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -24,7 +24,7 @@ export const firecrawlEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.firecrawl()` | | Verification | HMAC-SHA256 in `x-firecrawl-signature` | diff --git a/docs/webhooks/providers/github.mdx b/docs/webhooks/providers/github.mdx index 0a4c5edccfe..d4a75ac5791 100644 --- a/docs/webhooks/providers/github.mdx +++ b/docs/webhooks/providers/github.mdx @@ -1,10 +1,10 @@ --- title: "GitHub webhooks" sidebarTitle: "GitHub" -description: "Receive GitHub webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in GitHub, and how to set the signing credential." +description: "Receive and verify GitHub webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-hub-signature-256 and run a task for each GitHub event, filtered on header.x-github-event." --- -**`webhooks.github()` verifies GitHub's signature on every request, so subscribers only receive genuine GitHub events.** +**`webhooks.github()` verifies the HMAC-SHA256 signature GitHub sends in `x-hub-signature-256` on every request.** ```ts /trigger/github.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -24,7 +24,7 @@ export const githubEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.github()` | | Verification | HMAC-SHA256 in `x-hub-signature-256` | diff --git a/docs/webhooks/providers/gitlab.mdx b/docs/webhooks/providers/gitlab.mdx index 919b53e0700..731fc2eaa98 100644 --- a/docs/webhooks/providers/gitlab.mdx +++ b/docs/webhooks/providers/gitlab.mdx @@ -1,10 +1,10 @@ --- title: "GitLab webhooks" sidebarTitle: "GitLab" -description: "Receive GitLab webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in GitLab, and how to set the signing credential." +description: "Receive and verify GitLab webhooks with Trigger.dev. Check the secret token in x-gitlab-token and run a task for each GitLab event." --- -**`webhooks.gitlab()` checks the secret token GitLab sends with every request, so subscribers only receive genuine GitLab events.** +**`webhooks.gitlab()` checks the secret token GitLab sends in `x-gitlab-token` on every request.** ```ts /trigger/gitlab.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -25,7 +25,7 @@ export const gitlabEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `header.x-gitlab-event`. -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.gitlab()` | | Verification | Shared secret in `x-gitlab-token` | diff --git a/docs/webhooks/providers/granola.mdx b/docs/webhooks/providers/granola.mdx index 972acf0d150..17f8618e6ad 100644 --- a/docs/webhooks/providers/granola.mdx +++ b/docs/webhooks/providers/granola.mdx @@ -1,10 +1,10 @@ --- title: "Granola webhooks" sidebarTitle: "Granola" -description: "Receive Granola webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Granola, and how to set the signing credential." +description: "Receive and verify Granola webhooks with Trigger.dev. Check the Standard Webhooks signature and run a task for each Granola event, filtered on event.event_type." --- -**`webhooks.granola()` verifies Granola's signature on every request, so subscribers only receive genuine Granola events.** +**`webhooks.granola()` verifies the Standard Webhooks signature Granola sends in the `webhook-*` headers on every request.** ```ts /trigger/granola.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -24,7 +24,7 @@ export const granolaEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.granola()` | | Verification | Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`) | diff --git a/docs/webhooks/providers/hookdeck.mdx b/docs/webhooks/providers/hookdeck.mdx index 99226a95420..9a5481f56c4 100644 --- a/docs/webhooks/providers/hookdeck.mdx +++ b/docs/webhooks/providers/hookdeck.mdx @@ -1,7 +1,7 @@ --- title: "Hookdeck webhooks" sidebarTitle: "Hookdeck" -description: "Receive Hookdeck webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Hookdeck, and how to set the signing credential." +description: "Receive webhooks that Hookdeck forwards from any provider. Check the HMAC-SHA256 signature in x-hookdeck-signature and run a Trigger.dev task for each event." --- **`webhooks.hookdeck()` verifies requests that a Hookdeck connection forwards, so you can put Hookdeck in front of any provider.** @@ -24,12 +24,12 @@ export const hookdeckEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.hookdeck()` | | Verification | HMAC-SHA256 in `x-hookdeck-signature` | | Credential | Signing secret issued by Hookdeck | -| Event type | `event.type` | +| Event type | The original provider's field, for example `event.type` for Stripe | | Hookdeck docs | [Hookdeck webhook docs](https://hookdeck.com/docs/authentication) | ## Set up Hookdeck diff --git a/docs/webhooks/providers/infisical.mdx b/docs/webhooks/providers/infisical.mdx index dc67082238a..aceb3514cd2 100644 --- a/docs/webhooks/providers/infisical.mdx +++ b/docs/webhooks/providers/infisical.mdx @@ -1,10 +1,10 @@ --- title: "Infisical webhooks" sidebarTitle: "Infisical" -description: "Receive Infisical webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Infisical, and how to set the signing credential." +description: "Receive and verify Infisical webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-infisical-signature and run a task for each Infisical event, filtered on event.event." --- -**`webhooks.infisical()` verifies Infisical's signature on every request, so subscribers only receive genuine Infisical events.** +**`webhooks.infisical()` verifies the HMAC-SHA256 signature Infisical sends in `x-infisical-signature` on every request.** ```ts /trigger/infisical.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -24,7 +24,7 @@ export const infisicalEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.infisical()` | | Verification | HMAC-SHA256 in `x-infisical-signature` | diff --git a/docs/webhooks/providers/intercom.mdx b/docs/webhooks/providers/intercom.mdx index 510c5be02a7..e2f2b55b220 100644 --- a/docs/webhooks/providers/intercom.mdx +++ b/docs/webhooks/providers/intercom.mdx @@ -1,10 +1,10 @@ --- title: "Intercom webhooks" sidebarTitle: "Intercom" -description: "Receive Intercom webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Intercom, and how to set the signing credential." +description: "Receive and verify Intercom webhooks with Trigger.dev. Check the HMAC-SHA1 signature in x-hub-signature and run a task for each Intercom event, filtered on event.topic." --- -**`webhooks.intercom()` verifies Intercom's signature on every request, so subscribers only receive genuine Intercom events.** +**`webhooks.intercom()` verifies the HMAC-SHA1 signature Intercom sends in `x-hub-signature` on every request.** ```ts /trigger/intercom.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -25,7 +25,7 @@ export const intercomEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.topic`. -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.intercom()` | | Verification | HMAC-SHA1 in `x-hub-signature` | diff --git a/docs/webhooks/providers/jira.mdx b/docs/webhooks/providers/jira.mdx index 522747f6f1e..bce81ede1fe 100644 --- a/docs/webhooks/providers/jira.mdx +++ b/docs/webhooks/providers/jira.mdx @@ -1,10 +1,10 @@ --- title: "Jira webhooks" sidebarTitle: "Jira" -description: "Receive Jira webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Jira, and how to set the signing credential." +description: "Receive and verify Jira webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-hub-signature and run a task for each Jira event, filtered on event.webhookEvent." --- -**`webhooks.jira()` verifies Jira's signature on every request, so subscribers only receive genuine Jira events.** +**`webhooks.jira()` verifies the HMAC-SHA256 signature Jira sends in `x-hub-signature` on every request.** ```ts /trigger/jira.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -25,7 +25,7 @@ export const jiraEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.webhookEvent`. -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.jira()` | | Verification | HMAC-SHA256 in `x-hub-signature` | diff --git a/docs/webhooks/providers/langfuse.mdx b/docs/webhooks/providers/langfuse.mdx index 8486bdd8016..89bc2c25c2f 100644 --- a/docs/webhooks/providers/langfuse.mdx +++ b/docs/webhooks/providers/langfuse.mdx @@ -1,10 +1,10 @@ --- title: "Langfuse webhooks" sidebarTitle: "Langfuse" -description: "Receive Langfuse webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Langfuse, and how to set the signing credential." +description: "Receive and verify Langfuse webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-langfuse-signature and run a task for each Langfuse event, filtered on event.type." --- -**`webhooks.langfuse()` verifies Langfuse's signature on every request, so subscribers only receive genuine Langfuse events.** +**`webhooks.langfuse()` verifies the HMAC-SHA256 signature Langfuse sends in `x-langfuse-signature` on every request.** ```ts /trigger/langfuse.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -24,7 +24,7 @@ export const langfuseEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.langfuse()` | | Verification | HMAC-SHA256 in `x-langfuse-signature` | diff --git a/docs/webhooks/providers/linear.mdx b/docs/webhooks/providers/linear.mdx index eb582f8ffc5..e278726b272 100644 --- a/docs/webhooks/providers/linear.mdx +++ b/docs/webhooks/providers/linear.mdx @@ -1,10 +1,10 @@ --- title: "Linear webhooks" sidebarTitle: "Linear" -description: "Receive Linear webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Linear, and how to set the signing credential." +description: "Receive and verify Linear webhooks with Trigger.dev. Check the HMAC-SHA256 signature in linear-signature and run a task for each Linear event, filtered on event.type." --- -**`webhooks.linear()` verifies Linear's signature on every request, so subscribers only receive genuine Linear events.** +**`webhooks.linear()` verifies the HMAC-SHA256 signature Linear sends in `linear-signature` on every request.** ```ts /trigger/linear.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -25,7 +25,7 @@ export const linearEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.type`. -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.linear()` | | Verification | HMAC-SHA256 in `linear-signature` | diff --git a/docs/webhooks/providers/loops.mdx b/docs/webhooks/providers/loops.mdx index 090bea5c131..380b0c8b191 100644 --- a/docs/webhooks/providers/loops.mdx +++ b/docs/webhooks/providers/loops.mdx @@ -1,10 +1,10 @@ --- title: "Loops webhooks" sidebarTitle: "Loops" -description: "Receive Loops webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Loops, and how to set the signing credential." +description: "Receive and verify Loops webhooks with Trigger.dev. Check the Standard Webhooks signature and run a task for each Loops event, filtered on event.eventName." --- -**`webhooks.loops()` verifies Loops's signature on every request, so subscribers only receive genuine Loops events.** +**`webhooks.loops()` verifies the Standard Webhooks signature Loops sends in the `webhook-*` headers on every request.** ```ts /trigger/loops.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -24,7 +24,7 @@ export const loopsEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.loops()` | | Verification | Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`) | diff --git a/docs/webhooks/providers/metronome.mdx b/docs/webhooks/providers/metronome.mdx index f21bd02f13c..a05cd902233 100644 --- a/docs/webhooks/providers/metronome.mdx +++ b/docs/webhooks/providers/metronome.mdx @@ -1,10 +1,10 @@ --- title: "Metronome webhooks" sidebarTitle: "Metronome" -description: "Receive Metronome webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Metronome, and how to set the signing credential." +description: "Receive and verify Metronome webhooks with Trigger.dev. Check the HMAC-SHA256 signature in metronome-webhook-signature and run a task for each Metronome event, filtered on event.type." --- -**`webhooks.metronome()` verifies Metronome's signature on every request, so subscribers only receive genuine Metronome events.** +**`webhooks.metronome()` verifies the HMAC-SHA256 signature Metronome sends in `metronome-webhook-signature` on every request.** ```ts /trigger/metronome.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -25,7 +25,7 @@ export const metronomeEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.type`. -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.metronome()` | | Verification | HMAC-SHA256 in `metronome-webhook-signature` | diff --git a/docs/webhooks/providers/mux.mdx b/docs/webhooks/providers/mux.mdx index f1b08c441ab..af6678f948f 100644 --- a/docs/webhooks/providers/mux.mdx +++ b/docs/webhooks/providers/mux.mdx @@ -1,10 +1,10 @@ --- title: "Mux webhooks" sidebarTitle: "Mux" -description: "Receive Mux webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Mux, and how to set the signing credential." +description: "Receive and verify Mux webhooks with Trigger.dev. Check the HMAC-SHA256 signature in mux-signature and run a task for each Mux event, filtered on event.type." --- -**`webhooks.mux()` verifies Mux's signature on every request, so subscribers only receive genuine Mux events.** +**`webhooks.mux()` verifies the HMAC-SHA256 signature Mux sends in `mux-signature` on every request.** ```ts /trigger/mux.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -24,7 +24,7 @@ export const muxEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.mux()` | | Verification | HMAC-SHA256 in `mux-signature` | diff --git a/docs/webhooks/providers/notion.mdx b/docs/webhooks/providers/notion.mdx index 52152bc29fc..be918877073 100644 --- a/docs/webhooks/providers/notion.mdx +++ b/docs/webhooks/providers/notion.mdx @@ -1,10 +1,10 @@ --- title: "Notion webhooks" sidebarTitle: "Notion" -description: "Receive Notion webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Notion, and how to set the signing credential." +description: "Receive and verify Notion webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-notion-signature and run a task for each Notion event, filtered on event.type." --- -**`webhooks.notion()` verifies Notion's signature on every request, so subscribers only receive genuine Notion events.** +**`webhooks.notion()` verifies the HMAC-SHA256 signature Notion sends in `x-notion-signature` on every request.** ```ts /trigger/notion.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -24,7 +24,7 @@ export const notionEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.notion()` | | Verification | HMAC-SHA256 in `x-notion-signature` | diff --git a/docs/webhooks/providers/openai.mdx b/docs/webhooks/providers/openai.mdx index df02aca162e..56be934513c 100644 --- a/docs/webhooks/providers/openai.mdx +++ b/docs/webhooks/providers/openai.mdx @@ -1,10 +1,10 @@ --- title: "OpenAI webhooks" sidebarTitle: "OpenAI" -description: "Receive OpenAI webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in OpenAI, and how to set the signing credential." +description: "Receive and verify OpenAI webhooks with Trigger.dev. Check the Standard Webhooks signature and run a task for each OpenAI event, filtered on event.type." --- -**`webhooks.openai()` verifies OpenAI's signature on every request, so subscribers only receive genuine OpenAI events.** +**`webhooks.openai()` verifies the Standard Webhooks signature OpenAI sends in the `webhook-*` headers on every request.** ```ts /trigger/openai.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -24,7 +24,7 @@ export const openaiEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.openai()` | | Verification | Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`) | diff --git a/docs/webhooks/providers/pagerduty.mdx b/docs/webhooks/providers/pagerduty.mdx index 563101bf179..e61892046eb 100644 --- a/docs/webhooks/providers/pagerduty.mdx +++ b/docs/webhooks/providers/pagerduty.mdx @@ -1,10 +1,10 @@ --- title: "PagerDuty webhooks" sidebarTitle: "PagerDuty" -description: "Receive PagerDuty webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in PagerDuty, and how to set the signing credential." +description: "Receive and verify PagerDuty webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-pagerduty-signature and run a task for each PagerDuty event, filtered on event.event.event_type." --- -**`webhooks.pagerduty()` verifies PagerDuty's signature on every request, so subscribers only receive genuine PagerDuty events.** +**`webhooks.pagerduty()` verifies the HMAC-SHA256 signature PagerDuty sends in `x-pagerduty-signature` on every request.** ```ts /trigger/pagerduty.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -24,7 +24,7 @@ export const pagerdutyEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.pagerduty()` | | Verification | HMAC-SHA256 in `x-pagerduty-signature` | diff --git a/docs/webhooks/providers/plain.mdx b/docs/webhooks/providers/plain.mdx index 3631be341d9..38bb200a1b3 100644 --- a/docs/webhooks/providers/plain.mdx +++ b/docs/webhooks/providers/plain.mdx @@ -1,10 +1,10 @@ --- title: "Plain webhooks" sidebarTitle: "Plain" -description: "Receive Plain webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Plain, and how to set the signing credential." +description: "Receive and verify Plain webhooks with Trigger.dev. Check the HMAC-SHA256 signature in plain-request-signature and run a task for each Plain event, filtered on event.type." --- -**`webhooks.plain()` verifies Plain's signature on every request, so subscribers only receive genuine Plain events.** +**`webhooks.plain()` verifies the HMAC-SHA256 signature Plain sends in `plain-request-signature` on every request.** ```ts /trigger/plain.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -24,7 +24,7 @@ export const plainEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.plain()` | | Verification | HMAC-SHA256 in `plain-request-signature` | diff --git a/docs/webhooks/providers/planetscale.mdx b/docs/webhooks/providers/planetscale.mdx index c0984d00a6f..e6575f3414f 100644 --- a/docs/webhooks/providers/planetscale.mdx +++ b/docs/webhooks/providers/planetscale.mdx @@ -1,10 +1,10 @@ --- title: "PlanetScale webhooks" sidebarTitle: "PlanetScale" -description: "Receive PlanetScale webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in PlanetScale, and how to set the signing credential." +description: "Receive and verify PlanetScale webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-planetscale-signature and run a task for each PlanetScale event, filtered on event.event." --- -**`webhooks.planetscale()` verifies PlanetScale's signature on every request, so subscribers only receive genuine PlanetScale events.** +**`webhooks.planetscale()` verifies the HMAC-SHA256 signature PlanetScale sends in `x-planetscale-signature` on every request.** ```ts /trigger/planetscale.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -24,7 +24,7 @@ export const planetscaleEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.planetscale()` | | Verification | HMAC-SHA256 in `x-planetscale-signature` | diff --git a/docs/webhooks/providers/recall-ai.mdx b/docs/webhooks/providers/recall-ai.mdx index a19bec0d832..1e986bca99b 100644 --- a/docs/webhooks/providers/recall-ai.mdx +++ b/docs/webhooks/providers/recall-ai.mdx @@ -1,10 +1,10 @@ --- title: "Recall.ai webhooks" sidebarTitle: "Recall.ai" -description: "Receive Recall.ai webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Recall.ai, and how to set the signing credential." +description: "Receive and verify Recall.ai webhooks with Trigger.dev. Check the Standard Webhooks signature and run a task for each Recall.ai event, filtered on event.event." --- -**`webhooks.recallai()` verifies Recall.ai's signature on every request, so subscribers only receive genuine Recall.ai events.** +**`webhooks.recallai()` verifies the Standard Webhooks signature Recall.ai sends in the `webhook-*` headers on every request.** ```ts /trigger/recall-ai.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -25,7 +25,7 @@ export const recallaiEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event`. -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.recallai()` | | Verification | Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`) | diff --git a/docs/webhooks/providers/replicate.mdx b/docs/webhooks/providers/replicate.mdx index f5d1693f8e9..5f18f1eb6b1 100644 --- a/docs/webhooks/providers/replicate.mdx +++ b/docs/webhooks/providers/replicate.mdx @@ -1,10 +1,10 @@ --- title: "Replicate webhooks" sidebarTitle: "Replicate" -description: "Receive Replicate webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Replicate, and how to set the signing credential." +description: "Receive and verify Replicate webhooks with Trigger.dev. Check the Standard Webhooks signature and run a task for each Replicate event, filtered on event.status." --- -**`webhooks.replicate()` verifies Replicate's signature on every request, so subscribers only receive genuine Replicate events.** +**`webhooks.replicate()` verifies the Standard Webhooks signature Replicate sends in the `webhook-*` headers on every request.** ```ts /trigger/replicate.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -25,7 +25,7 @@ export const replicateEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.status`. -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.replicate()` | | Verification | Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`) | diff --git a/docs/webhooks/providers/resend.mdx b/docs/webhooks/providers/resend.mdx index 2d5b91d65ca..f4b2a01f338 100644 --- a/docs/webhooks/providers/resend.mdx +++ b/docs/webhooks/providers/resend.mdx @@ -1,10 +1,10 @@ --- title: "Resend webhooks" sidebarTitle: "Resend" -description: "Receive Resend webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Resend, and how to set the signing credential." +description: "Receive and verify Resend webhooks with Trigger.dev. Check the Svix signature and run a task for each Resend event, filtered on event.type." --- -**`webhooks.resend()` verifies Resend's signature on every request, so subscribers only receive genuine Resend events.** +**`webhooks.resend()` verifies the Svix signature Resend sends in the `svix-*` headers on every request.** ```ts /trigger/resend.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -24,7 +24,7 @@ export const resendEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.resend()` | | Verification | Svix (`svix-id`, `svix-timestamp`, `svix-signature`) | diff --git a/docs/webhooks/providers/retell.mdx b/docs/webhooks/providers/retell.mdx index 8f892153381..577c633c5c0 100644 --- a/docs/webhooks/providers/retell.mdx +++ b/docs/webhooks/providers/retell.mdx @@ -1,10 +1,10 @@ --- title: "Retell AI webhooks" sidebarTitle: "Retell AI" -description: "Receive Retell AI webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Retell AI, and how to set the signing credential." +description: "Receive and verify Retell AI webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-retell-signature and run a task for each Retell AI event, filtered on event.event." --- -**`webhooks.retell()` verifies Retell AI's signature on every request, so subscribers only receive genuine Retell AI events.** +**`webhooks.retell()` verifies the HMAC-SHA256 signature Retell AI sends in `x-retell-signature` on every request.** ```ts /trigger/retell.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -25,7 +25,7 @@ export const retellEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event`. -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.retell()` | | Verification | HMAC-SHA256 in `x-retell-signature` | diff --git a/docs/webhooks/providers/sentry.mdx b/docs/webhooks/providers/sentry.mdx index f0dbeeaf7c6..2edd8a540bc 100644 --- a/docs/webhooks/providers/sentry.mdx +++ b/docs/webhooks/providers/sentry.mdx @@ -1,10 +1,10 @@ --- title: "Sentry webhooks" sidebarTitle: "Sentry" -description: "Receive Sentry webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Sentry, and how to set the signing credential." +description: "Receive and verify Sentry webhooks with Trigger.dev. Check the HMAC-SHA256 signature in sentry-hook-signature and run a task for each Sentry event, filtered on header.sentry-hook-resource." --- -**`webhooks.sentry()` verifies Sentry's signature on every request, so subscribers only receive genuine Sentry events.** +**`webhooks.sentry()` verifies the HMAC-SHA256 signature Sentry sends in `sentry-hook-signature` on every request.** ```ts /trigger/sentry.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -25,7 +25,7 @@ export const sentryEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `header.sentry-hook-resource`. -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.sentry()` | | Verification | HMAC-SHA256 in `sentry-hook-signature` | diff --git a/docs/webhooks/providers/shopify.mdx b/docs/webhooks/providers/shopify.mdx index 8d5fe56dead..0953dad3d44 100644 --- a/docs/webhooks/providers/shopify.mdx +++ b/docs/webhooks/providers/shopify.mdx @@ -1,10 +1,10 @@ --- title: "Shopify webhooks" sidebarTitle: "Shopify" -description: "Receive Shopify webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Shopify, and how to set the signing credential." +description: "Receive and verify Shopify webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-shopify-hmac-sha256 and run a task for each Shopify event, filtered on header.x-shopify-topic." --- -**`webhooks.shopify()` verifies Shopify's signature on every request, so subscribers only receive genuine Shopify events.** +**`webhooks.shopify()` verifies the HMAC-SHA256 signature Shopify sends in `x-shopify-hmac-sha256` on every request.** ```ts /trigger/shopify.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -24,7 +24,7 @@ export const shopifyEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.shopify()` | | Verification | HMAC-SHA256 in `x-shopify-hmac-sha256` | diff --git a/docs/webhooks/providers/slack.mdx b/docs/webhooks/providers/slack.mdx index b545d7fd36d..95555fcbbf9 100644 --- a/docs/webhooks/providers/slack.mdx +++ b/docs/webhooks/providers/slack.mdx @@ -1,10 +1,10 @@ --- title: "Slack webhooks" sidebarTitle: "Slack" -description: "Receive Slack webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Slack, and how to set the signing credential." +description: "Receive and verify Slack webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-slack-signature and run a task for each Slack event, filtered on event.event.type." --- -**`webhookSource()` from `@trigger.dev/slack` verifies Slack's signature on every request, so subscribers only receive genuine Slack events.** +**`webhookSource()` from `@trigger.dev/slack` verifies the HMAC-SHA256 signature Slack sends in `x-slack-signature` on every request.** ```ts /trigger/slack.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -26,7 +26,7 @@ export const slackEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event.type`. -| | | +| Setting | Value | | --- | --- | | Source | `webhookSource()` from `@trigger.dev/slack` | | Verification | HMAC-SHA256 in `x-slack-signature`, with a timestamp tolerance | diff --git a/docs/webhooks/providers/square.mdx b/docs/webhooks/providers/square.mdx index 554b1ce3d9e..ee5df974c53 100644 --- a/docs/webhooks/providers/square.mdx +++ b/docs/webhooks/providers/square.mdx @@ -1,10 +1,10 @@ --- title: "Square webhooks" sidebarTitle: "Square" -description: "Receive Square webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Square, and how to set the signing credential." +description: "Receive and verify Square webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-square-hmacsha256-signature and run a task for each Square event, filtered on event.type." --- -**`webhooks.square()` verifies Square's signature on every request, so subscribers only receive genuine Square events.** +**`webhooks.square()` verifies the HMAC-SHA256 signature Square sends in `x-square-hmacsha256-signature` on every request.** ```ts /trigger/square.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -24,7 +24,7 @@ export const squareEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.square()` | | Verification | HMAC-SHA256 in `x-square-hmacsha256-signature` | diff --git a/docs/webhooks/providers/stripe.mdx b/docs/webhooks/providers/stripe.mdx index 34434400467..d550d2e22b6 100644 --- a/docs/webhooks/providers/stripe.mdx +++ b/docs/webhooks/providers/stripe.mdx @@ -4,7 +4,7 @@ sidebarTitle: "Stripe" description: "Verify Stripe's webhook signature and run a Trigger.dev task for each Stripe event, such as checkout.session.completed. Register the endpoint in Stripe, set the whsec_ signing secret, and filter by event type." --- -**`webhooks.stripe()` verifies the `stripe-signature` header on every request, so subscribers only receive genuine Stripe events.** +**`webhooks.stripe()` verifies the HMAC-SHA256 signature Stripe sends in `stripe-signature` on every request.** ```ts /trigger/stripe.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -24,7 +24,7 @@ export const fulfillCheckout = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.stripe()` | | Verification | HMAC-SHA256 in `stripe-signature`, with a timestamp tolerance | diff --git a/docs/webhooks/providers/supabase.mdx b/docs/webhooks/providers/supabase.mdx index 58cb562de89..679bcf52efd 100644 --- a/docs/webhooks/providers/supabase.mdx +++ b/docs/webhooks/providers/supabase.mdx @@ -1,7 +1,7 @@ --- title: "Supabase webhooks" sidebarTitle: "Supabase" -description: "Receive Supabase webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Supabase, and how to set the signing credential." +description: "Receive Supabase database webhooks with Trigger.dev. Check a shared bearer secret and run a task for each insert, update or delete." --- **`webhooks.supabase()` checks a shared secret on every request, because Supabase database webhooks aren't signed.** @@ -24,7 +24,7 @@ export const supabaseEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.supabase()` | | Verification | Shared secret as `Authorization: Bearer` | diff --git a/docs/webhooks/providers/tailscale.mdx b/docs/webhooks/providers/tailscale.mdx index 02ee1d87881..60dc96b54b2 100644 --- a/docs/webhooks/providers/tailscale.mdx +++ b/docs/webhooks/providers/tailscale.mdx @@ -1,10 +1,10 @@ --- title: "Tailscale webhooks" sidebarTitle: "Tailscale" -description: "Receive Tailscale webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Tailscale, and how to set the signing credential." +description: "Receive and verify Tailscale webhooks with Trigger.dev. Check the HMAC-SHA256 signature in tailscale-webhook-signature and run a task for each Tailscale event." --- -**`webhooks.tailscale()` verifies Tailscale's signature on every request, so subscribers only receive genuine Tailscale events.** +**`webhooks.tailscale()` verifies the HMAC-SHA256 signature Tailscale sends in `tailscale-webhook-signature` on every request.** ```ts /trigger/tailscale.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -24,7 +24,7 @@ export const tailscaleEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.tailscale()` | | Verification | HMAC-SHA256 in `tailscale-webhook-signature` | diff --git a/docs/webhooks/providers/typeform.mdx b/docs/webhooks/providers/typeform.mdx index 3235ac2b06c..dd2b26cf771 100644 --- a/docs/webhooks/providers/typeform.mdx +++ b/docs/webhooks/providers/typeform.mdx @@ -1,10 +1,10 @@ --- title: "Typeform webhooks" sidebarTitle: "Typeform" -description: "Receive Typeform webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Typeform, and how to set the signing credential." +description: "Receive and verify Typeform webhooks with Trigger.dev. Check the HMAC-SHA256 signature in typeform-signature and run a task for each Typeform event, filtered on event.event_type." --- -**`webhooks.typeform()` verifies Typeform's signature on every request, so subscribers only receive genuine Typeform events.** +**`webhooks.typeform()` verifies the HMAC-SHA256 signature Typeform sends in `typeform-signature` on every request.** ```ts /trigger/typeform.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -25,7 +25,7 @@ export const typeformEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event_type`. -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.typeform()` | | Verification | HMAC-SHA256 in `typeform-signature` | diff --git a/docs/webhooks/providers/vapi.mdx b/docs/webhooks/providers/vapi.mdx index 5b9f1a3070b..b438be206a4 100644 --- a/docs/webhooks/providers/vapi.mdx +++ b/docs/webhooks/providers/vapi.mdx @@ -1,10 +1,10 @@ --- title: "Vapi webhooks" sidebarTitle: "Vapi" -description: "Receive Vapi webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Vapi, and how to set the signing credential." +description: "Receive and verify Vapi webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-vapi-signature and run a task for each Vapi event, filtered on event.message.type." --- -**`webhooks.vapi()` verifies Vapi's signature on every request, so subscribers only receive genuine Vapi events.** +**`webhooks.vapi()` verifies the HMAC-SHA256 signature Vapi sends in `x-vapi-signature` on every request.** ```ts /trigger/vapi.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -25,7 +25,7 @@ export const vapiEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.message.type`. -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.vapi()` | | Verification | HMAC-SHA256 in `x-vapi-signature` | diff --git a/docs/webhooks/providers/vercel.mdx b/docs/webhooks/providers/vercel.mdx index cb370c11f42..2a8f3b091fb 100644 --- a/docs/webhooks/providers/vercel.mdx +++ b/docs/webhooks/providers/vercel.mdx @@ -1,10 +1,10 @@ --- title: "Vercel webhooks" sidebarTitle: "Vercel" -description: "Receive Vercel webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Vercel, and how to set the signing credential." +description: "Receive and verify Vercel webhooks with Trigger.dev. Check the HMAC-SHA1 signature in x-vercel-signature and run a task for each Vercel event, filtered on event.type." --- -**`webhooks.vercel()` verifies Vercel's signature on every request, so subscribers only receive genuine Vercel events.** +**`webhooks.vercel()` verifies the HMAC-SHA1 signature Vercel sends in `x-vercel-signature` on every request.** ```ts /trigger/vercel.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -24,7 +24,7 @@ export const vercelEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.vercel()` | | Verification | HMAC-SHA1 in `x-vercel-signature` | diff --git a/docs/webhooks/providers/whatsapp.mdx b/docs/webhooks/providers/whatsapp.mdx index 9ab52b209cb..fa95624b1c1 100644 --- a/docs/webhooks/providers/whatsapp.mdx +++ b/docs/webhooks/providers/whatsapp.mdx @@ -1,10 +1,10 @@ --- title: "WhatsApp webhooks" sidebarTitle: "WhatsApp" -description: "Receive WhatsApp webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in WhatsApp, and how to set the signing credential." +description: "Receive and verify WhatsApp webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-hub-signature-256 and run a task for each WhatsApp event." --- -**`webhooks.whatsapp()` verifies WhatsApp's signature on every request, so subscribers only receive genuine WhatsApp events.** +**`webhooks.whatsapp()` verifies the HMAC-SHA256 signature WhatsApp sends in `x-hub-signature-256`, keyed by the App Secret on every request.** ```ts /trigger/whatsapp.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -23,7 +23,7 @@ export const whatsappEvents = webhook({ }); ``` -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.whatsapp()` | | Verification | HMAC-SHA256 in `x-hub-signature-256`, keyed by the App Secret | diff --git a/docs/webhooks/providers/workos.mdx b/docs/webhooks/providers/workos.mdx index c30a62df9dc..eb49fa070f9 100644 --- a/docs/webhooks/providers/workos.mdx +++ b/docs/webhooks/providers/workos.mdx @@ -1,10 +1,10 @@ --- title: "WorkOS webhooks" sidebarTitle: "WorkOS" -description: "Receive WorkOS webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in WorkOS, and how to set the signing credential." +description: "Receive and verify WorkOS webhooks with Trigger.dev. Check the HMAC-SHA256 signature in workos-signature and run a task for each WorkOS event, filtered on event.event." --- -**`webhooks.workos()` verifies WorkOS's signature on every request, so subscribers only receive genuine WorkOS events.** +**`webhooks.workos()` verifies the HMAC-SHA256 signature WorkOS sends in `workos-signature` on every request.** ```ts /trigger/workos.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -25,7 +25,7 @@ export const workosEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event`. -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.workos()` | | Verification | HMAC-SHA256 in `workos-signature` | diff --git a/docs/webhooks/providers/zendesk.mdx b/docs/webhooks/providers/zendesk.mdx index 144f90ad37f..b1740fb6d2c 100644 --- a/docs/webhooks/providers/zendesk.mdx +++ b/docs/webhooks/providers/zendesk.mdx @@ -1,10 +1,10 @@ --- title: "Zendesk webhooks" sidebarTitle: "Zendesk" -description: "Receive Zendesk webhooks on a hosted Trigger.dev endpoint: the source, where to register the URL in Zendesk, and how to set the signing credential." +description: "Receive and verify Zendesk webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-zendesk-webhook-signature and run a task for each Zendesk event, filtered on event.status." --- -**`webhooks.zendesk()` verifies Zendesk's signature on every request, so subscribers only receive genuine Zendesk events.** +**`webhooks.zendesk()` verifies the HMAC-SHA256 signature Zendesk sends in `x-zendesk-webhook-signature` on every request.** ```ts /trigger/zendesk.ts import { webhook, webhooks } from "@trigger.dev/sdk"; @@ -25,7 +25,7 @@ export const zendeskEvents = webhook({ To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.status`. -| | | +| Setting | Value | | --- | --- | | Source | `webhooks.zendesk()` | | Verification | HMAC-SHA256 in `x-zendesk-webhook-signature` | diff --git a/docs/webhooks/session-routing.mdx b/docs/webhooks/session-routing.mdx index a3cf587cb25..8f6e62d5872 100644 --- a/docs/webhooks/session-routing.mdx +++ b/docs/webhooks/session-routing.mdx @@ -4,7 +4,7 @@ description: "Route verified webhook deliveries to a durable per-key session ins sidebarTitle: "Session routing" --- -A plain [`webhook()`](/webhooks/overview) runs a fresh, stateless run for every delivery. Sometimes you want the opposite: deliveries that share a key (a customer, an installation, an issue) should land on **one durable [session](/ai-chat/sessions)** and be handled in order, with state carried across them. That is what session routing does. +**Session routing sends deliveries that share a key (a customer, an installation, an issue) to one durable [session](/ai-chat/sessions), handled in order with state carried across them.** A plain [`webhook()`](/webhooks/overview) starts a fresh, stateless run for every delivery instead. Instead of a handler, you declare a `chat.event` on an [endpoint](/webhooks/overview) and list it on an agent. The verified delivery is routed to a find-or-created session and arrives as an [action](/ai-chat/actions). @@ -41,7 +41,7 @@ The `key` is what makes routing durable: two deliveries that resolve to the same These are the same namespaces [filter](/webhooks/filters) expressions use. Every placeholder names one: a bare `{customer}` is an error. -`{a || b}` falls back to `b` when `a` is missing or empty. Compose several placeholders into one key: `"{webhook.externalRef}-{event.issue.id}"`. Each placeholder is checked against the event type at build time, so a bad field is a red squiggle on the `key` line, not a runtime surprise. +`{a || b}` falls back to `b` when `a` is missing or empty. Compose several placeholders into one key: `"{webhook.externalRef}-{event.issue.id}"`. Each placeholder is checked against the event type at build time, so a bad field is a type error at build time. ### The `type` label @@ -74,7 +74,7 @@ export const orderAgent = chat.agent({ `action.type` is a closed union of the `type` labels of the events you listed, and each arm narrows `action.event` to that event's payload type. The full envelope is `{ type, event, source, headers, deliveryId, externalDeliveryId, endpoint }`. `deliveryId` is the delivery's `whd_` id, as in the dashboard and the [deliveries API](/webhooks/deliveries): a [replay](/webhooks/deliveries#replay) gets a new one. `externalDeliveryId` is the provider's id for the delivery (Stripe's `evt_` id, for example), the same across replays. `endpoint` is the endpoint the delivery arrived on. -Because it is an [action](/ai-chat/actions), the handler is not a turn by default: it can read the event, mutate session state with `chat.history`, and return nothing. To have the agent answer, return `chat.turn()`: the edit is saved, then a full turn runs on the session's history exactly as a message turn does. Webhook actions bypass your `actionSchema` (their shape is fixed and already verified by the source), so `action.type` and `action.event` are typed from the descriptor, not the schema. +Because it is an [action](/ai-chat/actions), the handler is not a turn by default: it can read the event, mutate session state with `chat.history`, and return nothing. To have the agent answer, return `chat.turn()`: the edit is saved, then a full turn runs on the session's history as a message turn does. Webhook actions bypass your `actionSchema` (their shape is fixed and already verified by the source), so `action.type` and `action.event` are typed from the descriptor, not the schema. ## Answering into a channel @@ -128,7 +128,7 @@ An exported `chat.event` that no agent lists routes nothing. `trigger dev` warns ## Filtering -A [`filter`](/webhooks/filters) works here exactly as on a `webhook()` task: a delivery that doesn't match never reaches the session, and the delivery records the reason. +A [`filter`](/webhooks/filters) works here as on a `webhook()` task: a delivery that doesn't match never reaches the session, and the delivery records the reason. ```ts export const orderEvents = chat.event({ diff --git a/docs/webhooks/slack.mdx b/docs/webhooks/slack.mdx index 6ff93f64cc8..81bd38665d2 100644 --- a/docs/webhooks/slack.mdx +++ b/docs/webhooks/slack.mdx @@ -247,7 +247,7 @@ Only buttons built with `button()` or `slackButton()` reach the agent. Buttons y ## Stopping -Slack shows a stop button while the agent is working. It aborts the running turn through the run's `signal`, exactly like a browser chat's stop: the model call and any tool that honours the signal stop, the partial reply stays in the thread, and the status goes back to active. The next message continues the conversation. +Slack shows a stop button while the agent is working. It aborts the running turn through the run's `signal`, as a browser chat's stop does: the model call and any tool that honors the signal stop, the partial reply stays in the thread, and the status goes back to active. The next message continues the conversation. - A stop pressed while nothing is running does nothing, and a repeated or delayed stop never stops a later turn. - A stop that reaches a session waiting on an approval cancels it: the buttons are replaced with "Stopped", the pending tool call is recorded as stopped so the model sees that on the next turn, and a later click resumes nothing. From 43b0fba53a21167cabfed9aa6e8eea53682e0755 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 16:03:24 +0000 Subject: [PATCH 30/37] docs: remove Notion, Brex and Intercom webhook provider pages Setup can't be completed for these providers yet, so drop their pages, table rows and sidebar entries, redirect the URLs to the providers list, and update the provider counts. --- docs/docs.json | 15 ++++++++-- docs/guides/introduction.mdx | 2 +- docs/snippets/examples-cards.mdx | 4 +-- docs/webhooks/deliveries.mdx | 4 +-- docs/webhooks/overview.mdx | 4 +-- docs/webhooks/providers.mdx | 3 -- docs/webhooks/providers/brex.mdx | 41 ---------------------------- docs/webhooks/providers/intercom.mdx | 41 ---------------------------- docs/webhooks/providers/notion.mdx | 40 --------------------------- 9 files changed, 19 insertions(+), 135 deletions(-) delete mode 100644 docs/webhooks/providers/brex.mdx delete mode 100644 docs/webhooks/providers/intercom.mdx delete mode 100644 docs/webhooks/providers/notion.mdx diff --git a/docs/docs.json b/docs/docs.json index e73c29e354c..122aec8d7ac 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -193,7 +193,6 @@ "webhooks/providers", "webhooks/providers/attio", "webhooks/providers/autumn", - "webhooks/providers/brex", "webhooks/providers/cal-com", "webhooks/providers/calendly", "webhooks/providers/clerk", @@ -207,14 +206,12 @@ "webhooks/providers/granola", "webhooks/providers/hookdeck", "webhooks/providers/infisical", - "webhooks/providers/intercom", "webhooks/providers/jira", "webhooks/providers/langfuse", "webhooks/providers/linear", "webhooks/providers/loops", "webhooks/providers/metronome", "webhooks/providers/mux", - "webhooks/providers/notion", "webhooks/providers/openai", "webhooks/providers/pagerduty", "webhooks/providers/plain", @@ -900,6 +897,18 @@ "source": "/guides/examples/hookdeck-webhook", "destination": "/webhooks/providers/hookdeck" }, + { + "source": "/webhooks/providers/notion", + "destination": "/webhooks/providers" + }, + { + "source": "/webhooks/providers/brex", + "destination": "/webhooks/providers" + }, + { + "source": "/webhooks/providers/intercom", + "destination": "/webhooks/providers" + }, { "source": "/webhooks/providers/zoom", "destination": "/webhooks/providers" diff --git a/docs/guides/introduction.mdx b/docs/guides/introduction.mdx index d26cbcf88f1..122693eb52c 100644 --- a/docs/guides/introduction.mdx +++ b/docs/guides/introduction.mdx @@ -37,7 +37,7 @@ Get set up fast using our detailed walk-through guides. | [Python PDF form extractor](/guides/python/python-pdf-form-extractor) | Use Python, PyMuPDF and Trigger.dev to extract data from a PDF form | | [Python web crawler](/guides/python/python-crawl4ai) | Use Python, Crawl4AI and Playwright to create a headless web crawler | | [Sequin database triggers](/guides/frameworks/sequin) | Trigger tasks from database changes using Sequin | -| [Receiving webhooks](/webhooks/providers) | Receive webhooks from Stripe, GitHub, Firecrawl and 40+ other providers | +| [Receiving webhooks](/webhooks/providers) | Receive webhooks from more than 40 providers, including Stripe and GitHub | | [Supabase database webhooks](/guides/frameworks/supabase-edge-functions-database-webhooks) | Trigger tasks using Supabase database webhooks | | [Supabase edge function hello world](/guides/frameworks/supabase-edge-functions-basic) | Trigger tasks from Supabase edge function | | [Custom webhook handler with Next.js](/guides/frameworks/nextjs-webhooks) | Trigger tasks from a webhook in Next.js | diff --git a/docs/snippets/examples-cards.mdx b/docs/snippets/examples-cards.mdx index 15d2dfadba0..567403a2b32 100644 --- a/docs/snippets/examples-cards.mdx +++ b/docs/snippets/examples-cards.mdx @@ -10,8 +10,8 @@ Deepgram, FFmpeg, Puppeteer, Supabase and more. - Receive webhooks from Stripe, GitHub, Firecrawl, Supabase and 40+ other providers on hosted - endpoints. + Receive webhooks from more than 40 providers, including Stripe, GitHub, Firecrawl and Supabase, + on hosted endpoints. Full-stack projects demonstrating how to use Trigger.dev. Fork them in GitHub as a starting diff --git a/docs/webhooks/deliveries.mdx b/docs/webhooks/deliveries.mdx index 387cc9fe14e..d87dbe75b73 100644 --- a/docs/webhooks/deliveries.mdx +++ b/docs/webhooks/deliveries.mdx @@ -89,8 +89,8 @@ When the source maps a provider event ID, that ID becomes the key, so the provid | Key | Providers | | --- | --- | -| A header | GitHub (`X-GitHub-Delivery`); Svix, Clerk, Resend, Brex and Autumn (`svix-id`); Standard Webhooks, OpenAI, Replicate, Recall.ai, Composio, Loops and Granola (`webhook-id`); Linear (`Linear-Delivery`); PagerDuty (`X-Webhook-Id`); Jira (`X-Atlassian-Webhook-Identifier`); Zendesk (`X-Zendesk-Webhook-Invocation-Id`); Attio (`Idempotency-Key`); Shopify (`X-Shopify-Webhook-Id`); Hookdeck (`X-Hookdeck-Eventid`, or `-eventid` with a custom header prefix) | -| A body field | Stripe, Notion, Vercel, Intercom, WorkOS, Metronome, Mux, Langfuse and Plain (`id`); Square, Slack and Typeform (`event_id`); Firecrawl (`webhookId`) | +| A header | GitHub (`X-GitHub-Delivery`); Svix, Clerk, Resend and Autumn (`svix-id`); Standard Webhooks, OpenAI, Replicate, Recall.ai, Composio, Loops and Granola (`webhook-id`); Linear (`Linear-Delivery`); PagerDuty (`X-Webhook-Id`); Jira (`X-Atlassian-Webhook-Identifier`); Zendesk (`X-Zendesk-Webhook-Invocation-Id`); Attio (`Idempotency-Key`); Shopify (`X-Shopify-Webhook-Id`); Hookdeck (`X-Hookdeck-Eventid`, or `-eventid` with a custom header prefix) | +| A body field | Stripe, Vercel, WorkOS, Metronome, Mux, Langfuse and Plain (`id`); Square, Slack and Typeform (`event_id`); Firecrawl (`webhookId`) | The other built-in providers (Calendly, Cal.com, Sentry, DocuSign, ElevenLabs, Vapi, Retell, Tailscale, Infisical, PlanetScale, Supabase, Discord, GitLab and WhatsApp) use the fallback below. diff --git a/docs/webhooks/overview.mdx b/docs/webhooks/overview.mdx index 6964cc748d2..6a94e70767e 100644 --- a/docs/webhooks/overview.mdx +++ b/docs/webhooks/overview.mdx @@ -15,7 +15,7 @@ Webhooks can start, resume or message your AI agents. [eric@trigger.dev](mailto:eric@trigger.dev) with the delivery id (`whd_...`) or run id. -[Built-in providers](/webhooks/providers) include Stripe, GitHub, Firecrawl, Linear and more than 40 others. For any other provider, define a [custom provider](/webhooks/custom-providers). If you prefer to handle webhooks in your own app, you can [trigger tasks from your own handler](/webhooks/own-handler). To set one up from scratch, follow the [quick start](/webhooks/quick-start). +There are more than 40 [built-in providers](/webhooks/providers), including Stripe, GitHub, Firecrawl and Linear. For any other provider, define a [custom provider](/webhooks/custom-providers). If you prefer to handle webhooks in your own app, you can [trigger tasks from your own handler](/webhooks/own-handler). To set one up from scratch, follow the [quick start](/webhooks/quick-start). Declare the endpoint once, then subscribe to it: @@ -64,7 +64,7 @@ Each subscriber has its own [filter](/webhooks/filters), so one delivery can rea Declare an endpoint and receive your first event. - Set up Stripe, GitHub, Firecrawl and 40+ other providers. + Set up more than 40 providers, including Stripe, GitHub and Firecrawl. What happens to a request, from verification to runs. diff --git a/docs/webhooks/providers.mdx b/docs/webhooks/providers.mdx index e5f846a8aa6..ab5ce561ef5 100644 --- a/docs/webhooks/providers.mdx +++ b/docs/webhooks/providers.mdx @@ -10,7 +10,6 @@ description: "Every built-in webhook provider, with its SDK function, the creden | --- | --- | --- | | [Attio](/webhooks/providers/attio) | `webhooks.attio()` | You generate it, or the provider issues it | | [Autumn](/webhooks/providers/autumn) | `webhooks.autumn()` | Issued by the provider | -| [Brex](/webhooks/providers/brex) | `webhooks.brex()` | Issued by the provider | | [Cal.com](/webhooks/providers/cal-com) | `webhooks.calCom()` | You generate it, or the provider issues it | | [Calendly](/webhooks/providers/calendly) | `webhooks.calendly()` | You choose it (OAuth apps: issued by the provider) | | [Clerk](/webhooks/providers/clerk) | `webhooks.clerk()` | Issued by the provider | @@ -24,14 +23,12 @@ description: "Every built-in webhook provider, with its SDK function, the creden | [Granola](/webhooks/providers/granola) | `webhooks.granola()` | Issued by the provider | | [Hookdeck](/webhooks/providers/hookdeck) | `webhooks.hookdeck()` | Issued by the provider | | [Infisical](/webhooks/providers/infisical) | `webhooks.infisical()` | You generate it | -| [Intercom](/webhooks/providers/intercom) | `webhooks.intercom()` | You generate it, or the provider issues it | | [Jira](/webhooks/providers/jira) | `webhooks.jira()` | You generate it, or the provider issues it | | [Langfuse](/webhooks/providers/langfuse) | `webhooks.langfuse()` | Issued by the provider | | [Linear](/webhooks/providers/linear) | `webhooks.linear()` | You generate it, or the provider issues it | | [Loops](/webhooks/providers/loops) | `webhooks.loops()` | Issued by the provider | | [Metronome](/webhooks/providers/metronome) | `webhooks.metronome()` | Issued by the provider | | [Mux](/webhooks/providers/mux) | `webhooks.mux()` | Issued by the provider | -| [Notion](/webhooks/providers/notion) | `webhooks.notion()` | Issued by the provider | | [OpenAI](/webhooks/providers/openai) | `webhooks.openai()` | Issued by the provider | | [PagerDuty](/webhooks/providers/pagerduty) | `webhooks.pagerduty()` | You generate it, or the provider issues it | | [Plain](/webhooks/providers/plain) | `webhooks.plain()` | Issued by the provider | diff --git a/docs/webhooks/providers/brex.mdx b/docs/webhooks/providers/brex.mdx deleted file mode 100644 index ca6de1ffc8a..00000000000 --- a/docs/webhooks/providers/brex.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: "Brex webhooks" -sidebarTitle: "Brex" -description: "Receive and verify Brex webhooks with Trigger.dev. Check the Svix signature and run a task for each Brex event, filtered on event.event_type." ---- - -**`webhooks.brex()` verifies the Svix signature Brex sends in the `svix-*` headers on every request.** - -```ts /trigger/brex.ts -import { webhook, webhooks } from "@trigger.dev/sdk"; - -export const brex = webhooks.endpoint.define({ - id: "brex", - source: webhooks.brex(), -}); - -export const brexEvents = webhook({ - id: "brex-events", - endpoint: brex, - onEvent: async ({ event }) => { - console.log(event); - }, -}); -``` - -To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event_type`. - -| Setting | Value | -| --- | --- | -| Source | `webhooks.brex()` | -| Verification | Svix (`svix-id`, `svix-timestamp`, `svix-signature`) | -| Credential | Signing secret from `GET /v1/webhooks/secrets` | -| Event type | `event.event_type` | -| Brex docs | [Brex webhook docs](https://developer.brex.com/guides/webhooks) | - -## Set up Brex - -1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Brex has no webhook settings page. Register the webhook URL with `POST /v1/webhooks`, passing `url` and the `event_types` your subscribers need. Brex allows one webhook endpoint per customer. -3. Get the signing secret from `GET /v1/webhooks/secrets`, then choose **Set signing secret** on the Trigger.dev endpoint and paste it. The secret has no `whsec_` prefix. During a key rotation the call returns two secrets; use the new one. -4. Send a test event from Brex, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/intercom.mdx b/docs/webhooks/providers/intercom.mdx deleted file mode 100644 index e2f2b55b220..00000000000 --- a/docs/webhooks/providers/intercom.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: "Intercom webhooks" -sidebarTitle: "Intercom" -description: "Receive and verify Intercom webhooks with Trigger.dev. Check the HMAC-SHA1 signature in x-hub-signature and run a task for each Intercom event, filtered on event.topic." ---- - -**`webhooks.intercom()` verifies the HMAC-SHA1 signature Intercom sends in `x-hub-signature` on every request.** - -```ts /trigger/intercom.ts -import { webhook, webhooks } from "@trigger.dev/sdk"; - -export const intercom = webhooks.endpoint.define({ - id: "intercom", - source: webhooks.intercom(), -}); - -export const intercomEvents = webhook({ - id: "intercom-events", - endpoint: intercom, - onEvent: async ({ event }) => { - console.log(event); - }, -}); -``` - -To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.topic`. - -| Setting | Value | -| --- | --- | -| Source | `webhooks.intercom()` | -| Verification | HMAC-SHA1 in `x-hub-signature` | -| Credential | Signing secret you generate on Trigger.dev, or one issued by Intercom | -| Event type | `event.topic` | -| Intercom docs | [Intercom webhook docs](https://developers.intercom.com/docs/references/webhooks/webhook-models) | - -## Set up Intercom - -1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as a webhook in Intercom and select the events your subscribers need. See Intercom's [webhook docs](https://developers.intercom.com/docs/references/webhooks/webhook-models) for where its webhook settings are. -3. If Intercom shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Intercom asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Intercom. -4. Send a test event from Intercom, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/notion.mdx b/docs/webhooks/providers/notion.mdx deleted file mode 100644 index be918877073..00000000000 --- a/docs/webhooks/providers/notion.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "Notion webhooks" -sidebarTitle: "Notion" -description: "Receive and verify Notion webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-notion-signature and run a task for each Notion event, filtered on event.type." ---- - -**`webhooks.notion()` verifies the HMAC-SHA256 signature Notion sends in `x-notion-signature` on every request.** - -```ts /trigger/notion.ts -import { webhook, webhooks } from "@trigger.dev/sdk"; - -export const notion = webhooks.endpoint.define({ - id: "notion", - source: webhooks.notion(), -}); - -export const notionEvents = webhook({ - id: "notion-events", - endpoint: notion, - filter: "event.type == 'page.created'", - onEvent: async ({ event }) => { - console.log(event); - }, -}); -``` - -| Setting | Value | -| --- | --- | -| Source | `webhooks.notion()` | -| Verification | HMAC-SHA256 in `x-notion-signature` | -| Credential | Signing secret issued by Notion | -| Event type | `event.type` | -| Notion docs | [Notion webhook docs](https://developers.notion.com/reference/webhooks) | - -## Set up Notion - -1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as a webhook in Notion and select the events your subscribers need. See Notion's [webhook docs](https://developers.notion.com/reference/webhooks) for where its webhook settings are. -3. Copy the signing secret Notion shows for the webhook, then choose **Set signing secret** on the Trigger.dev endpoint. -4. Send a test event from Notion, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. From 73c94b98fb86d6479c968403135b756a2b51fd40 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 16:13:07 +0000 Subject: [PATCH 31/37] docs: give nine webhook providers a single secret setup step Replace the conditional secret step on the Attio, Cal.com, Jira, Linear, PagerDuty, Sentry, Typeform, Vercel and Zendesk pages with each provider's actual flow and menu path. --- docs/webhooks/providers.mdx | 18 +++++++++--------- docs/webhooks/providers/attio.mdx | 6 +++--- docs/webhooks/providers/cal-com.mdx | 6 +++--- docs/webhooks/providers/jira.mdx | 6 +++--- docs/webhooks/providers/linear.mdx | 6 +++--- docs/webhooks/providers/pagerduty.mdx | 6 +++--- docs/webhooks/providers/sentry.mdx | 6 +++--- docs/webhooks/providers/typeform.mdx | 6 +++--- docs/webhooks/providers/vercel.mdx | 6 +++--- docs/webhooks/providers/zendesk.mdx | 6 +++--- 10 files changed, 36 insertions(+), 36 deletions(-) diff --git a/docs/webhooks/providers.mdx b/docs/webhooks/providers.mdx index ab5ce561ef5..3edf9ccd141 100644 --- a/docs/webhooks/providers.mdx +++ b/docs/webhooks/providers.mdx @@ -8,9 +8,9 @@ description: "Every built-in webhook provider, with its SDK function, the creden | Provider | Source | Credential | | --- | --- | --- | -| [Attio](/webhooks/providers/attio) | `webhooks.attio()` | You generate it, or the provider issues it | +| [Attio](/webhooks/providers/attio) | `webhooks.attio()` | Issued by the provider | | [Autumn](/webhooks/providers/autumn) | `webhooks.autumn()` | Issued by the provider | -| [Cal.com](/webhooks/providers/cal-com) | `webhooks.calCom()` | You generate it, or the provider issues it | +| [Cal.com](/webhooks/providers/cal-com) | `webhooks.calCom()` | You generate it | | [Calendly](/webhooks/providers/calendly) | `webhooks.calendly()` | You choose it (OAuth apps: issued by the provider) | | [Clerk](/webhooks/providers/clerk) | `webhooks.clerk()` | Issued by the provider | | [Composio](/webhooks/providers/composio) | `webhooks.composio()` | Issued by the provider | @@ -23,32 +23,32 @@ description: "Every built-in webhook provider, with its SDK function, the creden | [Granola](/webhooks/providers/granola) | `webhooks.granola()` | Issued by the provider | | [Hookdeck](/webhooks/providers/hookdeck) | `webhooks.hookdeck()` | Issued by the provider | | [Infisical](/webhooks/providers/infisical) | `webhooks.infisical()` | You generate it | -| [Jira](/webhooks/providers/jira) | `webhooks.jira()` | You generate it, or the provider issues it | +| [Jira](/webhooks/providers/jira) | `webhooks.jira()` | You generate it | | [Langfuse](/webhooks/providers/langfuse) | `webhooks.langfuse()` | Issued by the provider | -| [Linear](/webhooks/providers/linear) | `webhooks.linear()` | You generate it, or the provider issues it | +| [Linear](/webhooks/providers/linear) | `webhooks.linear()` | Issued by the provider | | [Loops](/webhooks/providers/loops) | `webhooks.loops()` | Issued by the provider | | [Metronome](/webhooks/providers/metronome) | `webhooks.metronome()` | Issued by the provider | | [Mux](/webhooks/providers/mux) | `webhooks.mux()` | Issued by the provider | | [OpenAI](/webhooks/providers/openai) | `webhooks.openai()` | Issued by the provider | -| [PagerDuty](/webhooks/providers/pagerduty) | `webhooks.pagerduty()` | You generate it, or the provider issues it | +| [PagerDuty](/webhooks/providers/pagerduty) | `webhooks.pagerduty()` | Issued by the provider | | [Plain](/webhooks/providers/plain) | `webhooks.plain()` | Issued by the provider | | [PlanetScale](/webhooks/providers/planetscale) | `webhooks.planetscale()` | Issued by the provider | | [Recall.ai](/webhooks/providers/recall-ai) | `webhooks.recallai()` | Issued by the provider | | [Replicate](/webhooks/providers/replicate) | `webhooks.replicate()` | Issued by the provider | | [Resend](/webhooks/providers/resend) | `webhooks.resend()` | Issued by the provider | | [Retell AI](/webhooks/providers/retell) | `webhooks.retell()` | Your API key with the webhook badge | -| [Sentry](/webhooks/providers/sentry) | `webhooks.sentry()` | You generate it, or the provider issues it | +| [Sentry](/webhooks/providers/sentry) | `webhooks.sentry()` | Issued by the provider | | [Shopify](/webhooks/providers/shopify) | `webhooks.shopify()` | Issued by the provider | | [Slack](/webhooks/providers/slack) | `webhookSource()` (`@trigger.dev/slack`) | Issued by the provider | | [Square](/webhooks/providers/square) | `webhooks.square()` | Issued by the provider | | [Stripe](/webhooks/providers/stripe) | `webhooks.stripe()` | Issued by the provider | | [Supabase](/webhooks/providers/supabase) | `webhooks.supabase()` | You generate it | | [Tailscale](/webhooks/providers/tailscale) | `webhooks.tailscale()` | Issued by the provider | -| [Typeform](/webhooks/providers/typeform) | `webhooks.typeform()` | You generate it, or the provider issues it | +| [Typeform](/webhooks/providers/typeform) | `webhooks.typeform()` | You generate it | | [Vapi](/webhooks/providers/vapi) | `webhooks.vapi()` | You generate it | -| [Vercel](/webhooks/providers/vercel) | `webhooks.vercel()` | You generate it, or the provider issues it | +| [Vercel](/webhooks/providers/vercel) | `webhooks.vercel()` | Issued by the provider | | [WhatsApp](/webhooks/providers/whatsapp) | `webhooks.whatsapp()` | Issued by the provider | | [WorkOS](/webhooks/providers/workos) | `webhooks.workos()` | Issued by the provider | -| [Zendesk](/webhooks/providers/zendesk) | `webhooks.zendesk()` | You generate it, or the provider issues it | +| [Zendesk](/webhooks/providers/zendesk) | `webhooks.zendesk()` | Issued by the provider | For a provider that isn't listed, define a [custom provider](/webhooks/custom-providers). For providers that sign with Svix or Standard Webhooks, `webhooks.svix()` and `webhooks.standardWebhooks()` also work; see [Verification](/webhooks/verification#svix-and-standard-webhooks). diff --git a/docs/webhooks/providers/attio.mdx b/docs/webhooks/providers/attio.mdx index 220fda2c0b3..fa7c47a2737 100644 --- a/docs/webhooks/providers/attio.mdx +++ b/docs/webhooks/providers/attio.mdx @@ -27,12 +27,12 @@ export const attioEvents = webhook({ | --- | --- | | Source | `webhooks.attio()` | | Verification | HMAC-SHA256 in `attio-signature` | -| Credential | Signing secret you generate on Trigger.dev, or one issued by Attio | +| Credential | Signing secret issued by Attio | | Attio docs | [Attio webhook docs](https://docs.attio.com/rest-api/guides/webhooks) | ## Set up Attio 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as a webhook in Attio and select the events your subscribers need. See Attio's [webhook docs](https://docs.attio.com/rest-api/guides/webhooks) for where its webhook settings are. -3. If Attio shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Attio asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Attio. +2. In Attio's developer settings, open your integration and add a webhook with the webhook URL and the events your subscribers need. You can also create it with Attio's webhooks API. +3. Attio generates the signing secret and returns it when the webhook is created; it's also shown in the developer settings. Copy it, then choose **Set signing secret** on the Trigger.dev endpoint. 4. Send a test event from Attio, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/cal-com.mdx b/docs/webhooks/providers/cal-com.mdx index 041a8a1ac2d..bea3b3f7ff2 100644 --- a/docs/webhooks/providers/cal-com.mdx +++ b/docs/webhooks/providers/cal-com.mdx @@ -29,13 +29,13 @@ To run a subscriber only for some events, add a [filter](/webhooks/filters) on ` | --- | --- | | Source | `webhooks.calCom()` | | Verification | HMAC-SHA256 in `x-cal-signature-256` | -| Credential | Signing secret you generate on Trigger.dev, or one issued by Cal.com | +| Credential | Secret you generate on Trigger.dev | | Event type | `event.triggerEvent` | | Cal.com docs | [Cal.com webhook docs](https://cal.com/docs/developing/guides/automation/webhooks) | ## Set up Cal.com 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as a webhook in Cal.com and select the events your subscribers need. See Cal.com's [webhook docs](https://cal.com/docs/developing/guides/automation/webhooks) for where its webhook settings are. -3. If Cal.com shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Cal.com asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Cal.com. +2. Choose **Generate secret** on the Trigger.dev endpoint and copy the value. +3. In Cal.com, open **Settings > Developer > Webhooks** and add a webhook with the webhook URL and the events your subscribers need. Paste the secret into its secret field. The secret is optional in Cal.com but required here: without it, Cal.com doesn't sign deliveries and every one is rejected. Cal.com hides the secret after you save. 4. Send a test event from Cal.com, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/jira.mdx b/docs/webhooks/providers/jira.mdx index bce81ede1fe..9ae139c65c9 100644 --- a/docs/webhooks/providers/jira.mdx +++ b/docs/webhooks/providers/jira.mdx @@ -29,13 +29,13 @@ To run a subscriber only for some events, add a [filter](/webhooks/filters) on ` | --- | --- | | Source | `webhooks.jira()` | | Verification | HMAC-SHA256 in `x-hub-signature` | -| Credential | Signing secret you generate on Trigger.dev, or one issued by Jira | +| Credential | Secret you generate on Trigger.dev | | Event type | `event.webhookEvent` | | Jira docs | [Jira webhook docs](https://developer.atlassian.com/cloud/jira/platform/webhooks/) | ## Set up Jira 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as a webhook in Jira and select the events your subscribers need. See Jira's [webhook docs](https://developer.atlassian.com/cloud/jira/platform/webhooks/) for where its webhook settings are. -3. If Jira shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Jira asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Jira. +2. Choose **Generate secret** on the Trigger.dev endpoint and copy the value. +3. As a Jira admin, open **System > WebHooks** and choose **Create a WebHook**. Enter the webhook URL, select the events your subscribers need, and paste the secret into **Secret**. Only webhooks an admin registers here are signed; webhooks registered by Connect or OAuth apps aren't, so the endpoint rejects them. 4. Send a test event from Jira, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/linear.mdx b/docs/webhooks/providers/linear.mdx index e278726b272..e7d986f4ae7 100644 --- a/docs/webhooks/providers/linear.mdx +++ b/docs/webhooks/providers/linear.mdx @@ -29,15 +29,15 @@ To run a subscriber only for some events, add a [filter](/webhooks/filters) on ` | --- | --- | | Source | `webhooks.linear()` | | Verification | HMAC-SHA256 in `linear-signature` | -| Credential | Signing secret you generate on Trigger.dev, or one issued by Linear | +| Credential | Signing secret issued by Linear | | Event type | `event.type` | | Linear docs | [Linear webhook docs](https://linear.app/developers/webhooks) | ## Set up Linear 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as a webhook in Linear and select the events your subscribers need. See Linear's [webhook docs](https://linear.app/developers/webhooks) for where its webhook settings are. -3. If Linear shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Linear asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Linear. +2. In Linear, open **Settings > API** and choose **New webhook**. Enter the webhook URL and select the resource types your subscribers need. +3. Linear generates the signing secret and shows it on the webhook's page. Copy it, then choose **Set signing secret** on the Trigger.dev endpoint. 4. Send a test event from Linear, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. ## Build a Linear agent diff --git a/docs/webhooks/providers/pagerduty.mdx b/docs/webhooks/providers/pagerduty.mdx index e61892046eb..5cae4ddb63f 100644 --- a/docs/webhooks/providers/pagerduty.mdx +++ b/docs/webhooks/providers/pagerduty.mdx @@ -28,13 +28,13 @@ export const pagerdutyEvents = webhook({ | --- | --- | | Source | `webhooks.pagerduty()` | | Verification | HMAC-SHA256 in `x-pagerduty-signature` | -| Credential | Signing secret you generate on Trigger.dev, or one issued by PagerDuty | +| Credential | Signing secret issued by PagerDuty | | Event type | `event.event.event_type` | | PagerDuty docs | [PagerDuty webhook docs](https://docs.pagerduty.com/developer/verifying-webhook-signatures) | ## Set up PagerDuty 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as a webhook in PagerDuty and select the events your subscribers need. See PagerDuty's [webhook docs](https://docs.pagerduty.com/developer/verifying-webhook-signatures) for where its webhook settings are. -3. If PagerDuty shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If PagerDuty asks you for a secret, choose **Generate secret** on the endpoint and paste the value into PagerDuty. +2. In PagerDuty, open **Integrations > Generic Webhooks (v3)** and choose **New Webhook**. Enter the webhook URL and select the event types your subscribers need. +3. PagerDuty shows the webhook's signing secret once, when the webhook is created. Copy it then, and choose **Set signing secret** on the Trigger.dev endpoint. 4. Send a test event from PagerDuty, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/sentry.mdx b/docs/webhooks/providers/sentry.mdx index 2edd8a540bc..f4fcd3fc024 100644 --- a/docs/webhooks/providers/sentry.mdx +++ b/docs/webhooks/providers/sentry.mdx @@ -29,13 +29,13 @@ To run a subscriber only for some events, add a [filter](/webhooks/filters) on ` | --- | --- | | Source | `webhooks.sentry()` | | Verification | HMAC-SHA256 in `sentry-hook-signature` | -| Credential | Signing secret you generate on Trigger.dev, or one issued by Sentry | +| Credential | The integration's Client Secret, issued by Sentry | | Event type | `header.sentry-hook-resource` | | Sentry docs | [Sentry webhook docs](https://docs.sentry.io/integrations/integration-platform/webhooks/) | ## Set up Sentry 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as a webhook in Sentry and select the events your subscribers need. See Sentry's [webhook docs](https://docs.sentry.io/integrations/integration-platform/webhooks/) for where its webhook settings are. -3. If Sentry shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Sentry asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Sentry. +2. In Sentry, open **Settings > Developer Settings > Custom Integrations** and create an internal integration. Set its **Webhook URL** to the webhook URL, turn on alert rule action if you want alerts, and enable the resource types (such as issue, error or comment) your subscribers need. +3. Sentry signs webhooks with the integration's **Client Secret**. Copy it from the integration's page, then choose **Set signing secret** on the Trigger.dev endpoint. 4. Send a test event from Sentry, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/typeform.mdx b/docs/webhooks/providers/typeform.mdx index dd2b26cf771..b3c73b3f0d6 100644 --- a/docs/webhooks/providers/typeform.mdx +++ b/docs/webhooks/providers/typeform.mdx @@ -29,13 +29,13 @@ To run a subscriber only for some events, add a [filter](/webhooks/filters) on ` | --- | --- | | Source | `webhooks.typeform()` | | Verification | HMAC-SHA256 in `typeform-signature` | -| Credential | Signing secret you generate on Trigger.dev, or one issued by Typeform | +| Credential | Secret you generate on Trigger.dev | | Event type | `event.event_type` | | Typeform docs | [Typeform webhook docs](https://www.typeform.com/developers/webhooks/secure-your-webhooks/) | ## Set up Typeform 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as a webhook in Typeform and select the events your subscribers need. See Typeform's [webhook docs](https://www.typeform.com/developers/webhooks/secure-your-webhooks/) for where its webhook settings are. -3. If Typeform shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Typeform asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Typeform. +2. Choose **Generate secret** on the Trigger.dev endpoint and copy the value. +3. In Typeform, open the form's **Connect > Webhooks** and add a webhook with the webhook URL. Edit it and paste the secret into **Secret**. You can also set `secret` when you create the webhook with Typeform's API. 4. Send a test event from Typeform, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/vercel.mdx b/docs/webhooks/providers/vercel.mdx index 2a8f3b091fb..0a002ec1375 100644 --- a/docs/webhooks/providers/vercel.mdx +++ b/docs/webhooks/providers/vercel.mdx @@ -28,13 +28,13 @@ export const vercelEvents = webhook({ | --- | --- | | Source | `webhooks.vercel()` | | Verification | HMAC-SHA1 in `x-vercel-signature` | -| Credential | Signing secret you generate on Trigger.dev, or one issued by Vercel | +| Credential | Signing secret issued by Vercel | | Event type | `event.type` | | Vercel docs | [Vercel webhook docs](https://vercel.com/docs/webhooks) | ## Set up Vercel 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as a webhook in Vercel and select the events your subscribers need. See Vercel's [webhook docs](https://vercel.com/docs/webhooks) for where its webhook settings are. -3. If Vercel shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Vercel asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Vercel. +2. In Vercel, open your team's **Settings > Webhooks** (Pro and Enterprise plans) and create a webhook with the webhook URL and the events your subscribers need. +3. Vercel shows the webhook's secret once, in the dialog after the webhook is created. Copy it then, and choose **Set signing secret** on the Trigger.dev endpoint. Webhooks from a Vercel integration are signed with the integration's Client Secret instead. 4. Send a test event from Vercel, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/zendesk.mdx b/docs/webhooks/providers/zendesk.mdx index b1740fb6d2c..55034504b17 100644 --- a/docs/webhooks/providers/zendesk.mdx +++ b/docs/webhooks/providers/zendesk.mdx @@ -29,13 +29,13 @@ To run a subscriber only for some events, add a [filter](/webhooks/filters) on ` | --- | --- | | Source | `webhooks.zendesk()` | | Verification | HMAC-SHA256 in `x-zendesk-webhook-signature` | -| Credential | Signing secret you generate on Trigger.dev, or one issued by Zendesk | +| Credential | Signing secret issued by Zendesk | | Event type | `event.status` | | Zendesk docs | [Zendesk webhook docs](https://developer.zendesk.com/documentation/webhooks/verifying/) | ## Set up Zendesk 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as a webhook in Zendesk and select the events your subscribers need. See Zendesk's [webhook docs](https://developer.zendesk.com/documentation/webhooks/verifying/) for where its webhook settings are. -3. If Zendesk shows a signing secret when you create the webhook, copy it and choose **Set signing secret** on the Trigger.dev endpoint. If Zendesk asks you for a secret, choose **Generate secret** on the endpoint and paste the value into Zendesk. +2. In Zendesk Admin Center, open **Apps and integrations > Webhooks** and create a webhook with the webhook URL. Subscribe it to Zendesk events, or connect it to a trigger or automation. +3. Zendesk generates the signing secret. On the webhook's details, choose **Reveal secret**, copy it, and choose **Set signing secret** on the Trigger.dev endpoint. 4. Send a test event from Zendesk, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. From a95e5d09e9cd67b68c07b4880045bfddba423b2e Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 16:23:59 +0000 Subject: [PATCH 32/37] docs: match the webhooks quick start to the dashboard Add the confirm step for Generate secret, the x-github-event header in the Test tab, deduplication of repeated test bodies, and the Targets view on a delivery, from a run-through on a fresh project. --- docs/webhooks/quick-start.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/webhooks/quick-start.mdx b/docs/webhooks/quick-start.mdx index b57a44982f2..b9fc68ca27b 100644 --- a/docs/webhooks/quick-start.mdx +++ b/docs/webhooks/quick-start.mdx @@ -103,13 +103,15 @@ The CLI registers the `github` endpoint you declared in your **Development** env In the [Trigger.dev dashboard](https://cloud.trigger.dev), open your project, make sure the **Development** environment is selected, and choose **Webhooks** in the side menu. The `github` endpoint is listed with its **Signing secret** column set to **Needs secret**. Every delivery is rejected until an endpoint has its secret. -Open the `github` endpoint and choose **Generate secret**. The secret is shown once: copy it if you'll connect GitHub later. Back on the **Webhooks** page, the column now says **Ready**. +Open the `github` endpoint, choose **Generate secret** and confirm. The secret is shown once: copy it if you'll connect GitHub later. Back on the **Webhooks** page, the column now says **Ready**. -On the `github` endpoint's page, open the **Test** tab, pick a sample event and choose **Send event**. The delivery appears on the **Deliveries** tab. Open it to see that it reached the `github-events` subscriber, then follow the link to the run to see the logged event. +On the `github` endpoint's page, open the **Test** tab. It starts with a sample body. Under **Headers**, add `x-github-event` with a value such as `push` so the handler logs an event name, then choose **Send event**. The test is signed with the endpoint's secret and runs the full delivery pipeline. Sending the same body again is deduplicated to the first delivery, so change the body to send another. + +The delivery appears on the **Deliveries** tab. Open it and check **Targets** to see that it reached the `github-events` subscriber, then follow the link to the run to see the logged event. From 803d23401f0656445245930bb5c4977056086990 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 16:27:30 +0000 Subject: [PATCH 33/37] chore: format docs.json --- docs/docs.json | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 122aec8d7ac..e6e2af1c076 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -254,10 +254,7 @@ { "group": "Deliveries and limits", "expanded": true, - "pages": [ - "webhooks/deliveries", - "webhooks/pricing-and-limits" - ] + "pages": ["webhooks/deliveries", "webhooks/pricing-and-limits"] } ] }, From 93d7f3226adac6cce45757d128caa60ce22c1f73 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 16:37:24 +0000 Subject: [PATCH 34/37] docs: restore the Hookdeck trigger API alternative --- docs/webhooks/providers/hookdeck.mdx | 29 ++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/webhooks/providers/hookdeck.mdx b/docs/webhooks/providers/hookdeck.mdx index 9a5481f56c4..146b8d76dab 100644 --- a/docs/webhooks/providers/hookdeck.mdx +++ b/docs/webhooks/providers/hookdeck.mdx @@ -67,3 +67,32 @@ export const paymentSucceeded = webhook({ - **Secret rotation:** when you roll the signing secret in Hookdeck with an expiry, Hookdeck also signs each request with the previous secret in `X-Hookdeck-Signature-2`, so deliveries keep verifying until you store the new secret. - **Deduplication:** retries dedupe on `X-Hookdeck-Eventid`, which is the same on every attempt of a Hookdeck event. - **Custom header prefix:** if you changed the header prefix in the Hookdeck project's settings, pass it with `webhooks.hookdeck({ headerPrefix: "x-acme" })`. The prefix renames the event id header; the signature headers keep the `X-Hookdeck-` name. + +## Trigger a task through the API instead + +You can also point a Hookdeck destination at the [trigger task API](/management/tasks/trigger) without a hosted endpoint. Hookdeck authenticates with your API key instead of a signature, and a transformation wraps the body in the `payload` field the API expects. + +1. Create a destination with the URL `https://api.trigger.dev/api/v1/tasks//trigger`, method `POST`, and **Bearer token** authentication using a [**Trigger only**](/apikeys) environment API key. +2. Add a [transformation](https://hookdeck.com/docs/transformations): + + ```javascript + addHandler("transform", (request, context) => { + request.body = { payload: { ...request.body } }; + return request; + }); + ``` + +3. Create a connection from your source to that destination and transformation. + +```ts /trigger/webhook-handler.ts +import { task } from "@trigger.dev/sdk"; + +export const webhookHandler = task({ + id: "webhook-handler", + run: async (payload: Record) => { + console.log("Received webhook:", payload); + }, +}); +``` + +This path doesn't deduplicate Hookdeck retries, so each forwarded request starts a run, and the delivery isn't recorded on a Trigger.dev endpoint. From 3dc74404c72606db375135873fcd14c64bdb30a1 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 16:47:10 +0000 Subject: [PATCH 35/37] docs: address webhooks review comments Keep batched bodies intact in the Hookdeck transformation, drop the Stripe-only filter from the generic Hookdeck example, add Slack's install step and Typeform's On switch, filter Zendesk on event.type, correct retry, header and ordering wording, and remove the Composio page until its secret format is supported. --- docs/docs.json | 5 +++- docs/webhooks/deliveries.mdx | 2 +- docs/webhooks/pricing-and-limits.mdx | 2 +- docs/webhooks/providers.mdx | 1 - docs/webhooks/providers/composio.mdx | 40 ---------------------------- docs/webhooks/providers/hookdeck.mdx | 3 +-- docs/webhooks/providers/slack.mdx | 3 ++- docs/webhooks/providers/typeform.mdx | 3 ++- docs/webhooks/providers/zendesk.mdx | 6 ++--- docs/webhooks/session-routing.mdx | 2 +- docs/webhooks/verification.mdx | 12 ++++----- docs/webhooks/webhook-tasks.mdx | 10 +++---- 12 files changed, 26 insertions(+), 63 deletions(-) delete mode 100644 docs/webhooks/providers/composio.mdx diff --git a/docs/docs.json b/docs/docs.json index e6e2af1c076..ff90f748016 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -196,7 +196,6 @@ "webhooks/providers/cal-com", "webhooks/providers/calendly", "webhooks/providers/clerk", - "webhooks/providers/composio", "webhooks/providers/discord", "webhooks/providers/docusign", "webhooks/providers/elevenlabs", @@ -906,6 +905,10 @@ "source": "/webhooks/providers/intercom", "destination": "/webhooks/providers" }, + { + "source": "/webhooks/providers/composio", + "destination": "/webhooks/providers" + }, { "source": "/webhooks/providers/zoom", "destination": "/webhooks/providers" diff --git a/docs/webhooks/deliveries.mdx b/docs/webhooks/deliveries.mdx index d87dbe75b73..e9d12b47426 100644 --- a/docs/webhooks/deliveries.mdx +++ b/docs/webhooks/deliveries.mdx @@ -89,7 +89,7 @@ When the source maps a provider event ID, that ID becomes the key, so the provid | Key | Providers | | --- | --- | -| A header | GitHub (`X-GitHub-Delivery`); Svix, Clerk, Resend and Autumn (`svix-id`); Standard Webhooks, OpenAI, Replicate, Recall.ai, Composio, Loops and Granola (`webhook-id`); Linear (`Linear-Delivery`); PagerDuty (`X-Webhook-Id`); Jira (`X-Atlassian-Webhook-Identifier`); Zendesk (`X-Zendesk-Webhook-Invocation-Id`); Attio (`Idempotency-Key`); Shopify (`X-Shopify-Webhook-Id`); Hookdeck (`X-Hookdeck-Eventid`, or `-eventid` with a custom header prefix) | +| A header | GitHub (`X-GitHub-Delivery`); Svix, Clerk, Resend and Autumn (`svix-id`); Standard Webhooks, OpenAI, Replicate, Recall.ai, Loops and Granola (`webhook-id`); Linear (`Linear-Delivery`); PagerDuty (`X-Webhook-Id`); Jira (`X-Atlassian-Webhook-Identifier`); Zendesk (`X-Zendesk-Webhook-Invocation-Id`); Attio (`Idempotency-Key`); Shopify (`X-Shopify-Webhook-Id`); Hookdeck (`X-Hookdeck-Eventid`, or `-eventid` with a custom header prefix) | | A body field | Stripe, Vercel, WorkOS, Metronome, Mux, Langfuse and Plain (`id`); Square, Slack and Typeform (`event_id`); Firecrawl (`webhookId`) | The other built-in providers (Calendly, Cal.com, Sentry, DocuSign, ElevenLabs, Vapi, Retell, Tailscale, Infisical, PlanetScale, Supabase, Discord, GitLab and WhatsApp) use the fallback below. diff --git a/docs/webhooks/pricing-and-limits.mdx b/docs/webhooks/pricing-and-limits.mdx index e49cb856e9f..037381db86a 100644 --- a/docs/webhooks/pricing-and-limits.mdx +++ b/docs/webhooks/pricing-and-limits.mdx @@ -6,7 +6,7 @@ description: "What webhooks cost on Trigger.dev Cloud, which plan limits apply, Webhooks have no separate charge on Trigger.dev Cloud. Receiving, verifying, filtering and recording deliveries is included in every plan. The runs a delivery starts or resumes are billed like any other run: a per-run invocation cost plus compute time. See [pricing](https://trigger.dev/pricing). -A delivery that no subscriber's filter matches starts no run for any subscriber, so it costs nothing. A run already waiting for that webhook still resumes. A run [waiting](/webhooks/waiters) for a webhook is suspended, so it uses no compute until the webhook arrives. +A delivery that no subscriber's filter matches starts no run, so it adds no run cost. A run already [waiting](/webhooks/waiters) for that webhook still resumes and is billed like any other run. A run [waiting](/webhooks/waiters) for a webhook is suspended, so it uses no compute until the webhook arrives. Each plan sets limits on the ingest rate, waiting runs, processing concurrency and how long deliveries are kept. See [Limits](/limits#webhook-ingest-rate-limits). diff --git a/docs/webhooks/providers.mdx b/docs/webhooks/providers.mdx index 3edf9ccd141..f325d06f74a 100644 --- a/docs/webhooks/providers.mdx +++ b/docs/webhooks/providers.mdx @@ -13,7 +13,6 @@ description: "Every built-in webhook provider, with its SDK function, the creden | [Cal.com](/webhooks/providers/cal-com) | `webhooks.calCom()` | You generate it | | [Calendly](/webhooks/providers/calendly) | `webhooks.calendly()` | You choose it (OAuth apps: issued by the provider) | | [Clerk](/webhooks/providers/clerk) | `webhooks.clerk()` | Issued by the provider | -| [Composio](/webhooks/providers/composio) | `webhooks.composio()` | Issued by the provider | | [Discord](/webhooks/providers/discord) | `webhooks.discord()` | Provider's public key | | [DocuSign](/webhooks/providers/docusign) | `webhooks.docusign()` | Issued by the provider | | [ElevenLabs](/webhooks/providers/elevenlabs) | `webhooks.elevenlabs()` | Issued by the provider | diff --git a/docs/webhooks/providers/composio.mdx b/docs/webhooks/providers/composio.mdx deleted file mode 100644 index 1da456d8864..00000000000 --- a/docs/webhooks/providers/composio.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: "Composio webhooks" -sidebarTitle: "Composio" -description: "Receive and verify Composio webhooks with Trigger.dev. Check the Standard Webhooks signature and run a task for each Composio event, filtered on event.type." ---- - -**`webhooks.composio()` verifies the Standard Webhooks signature Composio sends in the `webhook-*` headers on every request.** - -```ts /trigger/composio.ts -import { webhook, webhooks } from "@trigger.dev/sdk"; - -export const composio = webhooks.endpoint.define({ - id: "composio", - source: webhooks.composio(), -}); - -export const composioEvents = webhook({ - id: "composio-events", - endpoint: composio, - onEvent: async ({ event }) => { - console.log(event); - }, -}); -``` - -To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.type`. - -| Setting | Value | -| --- | --- | -| Source | `webhooks.composio()` | -| Verification | Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`) | -| Credential | Signing secret issued by Composio | -| Event type | `event.type` | - -## Set up Composio - -1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. -2. Add the webhook URL as an endpoint in Composio's webhook settings and subscribe it to the event types your subscribers need. -3. Copy the endpoint's signing secret (it starts with `whsec_`), then choose **Set signing secret** on the Trigger.dev endpoint. -4. Send a test event from Composio, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/hookdeck.mdx b/docs/webhooks/providers/hookdeck.mdx index 146b8d76dab..98d475ca2e8 100644 --- a/docs/webhooks/providers/hookdeck.mdx +++ b/docs/webhooks/providers/hookdeck.mdx @@ -17,7 +17,6 @@ export const hookdeck = webhooks.endpoint.define({ export const hookdeckEvents = webhook({ id: "hookdeck-events", endpoint: hookdeck, - filter: "event.type == 'payment_intent.succeeded'", onEvent: async ({ event }) => { console.log(event); }, @@ -77,7 +76,7 @@ You can also point a Hookdeck destination at the [trigger task API](/management/ ```javascript addHandler("transform", (request, context) => { - request.body = { payload: { ...request.body } }; + request.body = { payload: request.body }; return request; }); ``` diff --git a/docs/webhooks/providers/slack.mdx b/docs/webhooks/providers/slack.mdx index 95555fcbbf9..edd3e0963f2 100644 --- a/docs/webhooks/providers/slack.mdx +++ b/docs/webhooks/providers/slack.mdx @@ -40,7 +40,8 @@ To run a subscriber only for some events, add a [filter](/webhooks/filters) on ` 2. In your Slack app's settings, set the **Event Subscriptions** request URL to the webhook URL and subscribe to the bot events your subscribers need. 3. Copy the app's **Signing Secret** from **Basic Information > App Credentials**, then choose **Set signing secret** on the Trigger.dev endpoint. 4. Back on the Event Subscriptions page, choose **Retry**. Slack's `url_verification` challenge is answered by the endpoint once the secret is set. -5. Send a test event from Slack, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. +5. Install the app to your workspace, or reinstall it if the bot events need new scopes. Slack only delivers events the workspace has authorized. +6. Send a test event from Slack, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. ## Build a Slack agent diff --git a/docs/webhooks/providers/typeform.mdx b/docs/webhooks/providers/typeform.mdx index b3c73b3f0d6..6f46d397da9 100644 --- a/docs/webhooks/providers/typeform.mdx +++ b/docs/webhooks/providers/typeform.mdx @@ -38,4 +38,5 @@ To run a subscriber only for some events, add a [filter](/webhooks/filters) on ` 1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. 2. Choose **Generate secret** on the Trigger.dev endpoint and copy the value. 3. In Typeform, open the form's **Connect > Webhooks** and add a webhook with the webhook URL. Edit it and paste the secret into **Secret**. You can also set `secret` when you create the webhook with Typeform's API. -4. Send a test event from Typeform, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. +4. Turn the webhook **On**. Typeform creates dashboard webhooks switched off. +5. Send a test event from Typeform, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/zendesk.mdx b/docs/webhooks/providers/zendesk.mdx index 55034504b17..9dc325f98a0 100644 --- a/docs/webhooks/providers/zendesk.mdx +++ b/docs/webhooks/providers/zendesk.mdx @@ -1,7 +1,7 @@ --- title: "Zendesk webhooks" sidebarTitle: "Zendesk" -description: "Receive and verify Zendesk webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-zendesk-webhook-signature and run a task for each Zendesk event, filtered on event.status." +description: "Receive and verify Zendesk webhooks with Trigger.dev. Check the HMAC-SHA256 signature in x-zendesk-webhook-signature and run a task for each Zendesk event, filtered on its event type." --- **`webhooks.zendesk()` verifies the HMAC-SHA256 signature Zendesk sends in `x-zendesk-webhook-signature` on every request.** @@ -23,14 +23,14 @@ export const zendeskEvents = webhook({ }); ``` -To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.status`. +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.type` for Zendesk event subscriptions. For trigger and automation webhooks, you write the JSON body, so filter on a field your template sends. | Setting | Value | | --- | --- | | Source | `webhooks.zendesk()` | | Verification | HMAC-SHA256 in `x-zendesk-webhook-signature` | | Credential | Signing secret issued by Zendesk | -| Event type | `event.status` | +| Event type | `event.type` for event subscriptions; a field from your template for triggers and automations | | Zendesk docs | [Zendesk webhook docs](https://developer.zendesk.com/documentation/webhooks/verifying/) | ## Set up Zendesk diff --git a/docs/webhooks/session-routing.mdx b/docs/webhooks/session-routing.mdx index 8f6e62d5872..df268768e01 100644 --- a/docs/webhooks/session-routing.mdx +++ b/docs/webhooks/session-routing.mdx @@ -4,7 +4,7 @@ description: "Route verified webhook deliveries to a durable per-key session ins sidebarTitle: "Session routing" --- -**Session routing sends deliveries that share a key (a customer, an installation, an issue) to one durable [session](/ai-chat/sessions), handled in order with state carried across them.** A plain [`webhook()`](/webhooks/overview) starts a fresh, stateless run for every delivery instead. +**Session routing sends deliveries that share a key (a customer, an installation, an issue) to one durable [session](/ai-chat/sessions), handled one at a time with state carried across them.** A plain [`webhook()`](/webhooks/overview) starts a fresh, stateless run for every delivery instead. Instead of a handler, you declare a `chat.event` on an [endpoint](/webhooks/overview) and list it on an agent. The verified delivery is routed to a find-or-created session and arrives as an [action](/ai-chat/actions). diff --git a/docs/webhooks/verification.mdx b/docs/webhooks/verification.mdx index 6b143aac904..b5dbabeb1e7 100644 --- a/docs/webhooks/verification.mdx +++ b/docs/webhooks/verification.mdx @@ -57,14 +57,14 @@ export const svixEvents = webhook({ }); ``` -```ts /trigger/composio.ts +```ts /trigger/my-provider.ts import { webhook, webhooks } from "@trigger.dev/sdk"; -export const composio = webhooks.endpoint.define({ id: "composio", source: webhooks.standardWebhooks() }); +export const myProvider = webhooks.endpoint.define({ id: "my-provider", source: webhooks.standardWebhooks() }); -export const composioEvents = webhook({ - id: "composio-events", - endpoint: composio, +export const myProviderEvents = webhook({ + id: "my-provider-events", + endpoint: myProvider, onEvent: async ({ event }) => { console.log(event); }, @@ -84,7 +84,7 @@ The available presets are `stripe()`, `github()`, `svix()`, `standardWebhooks()` | `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 sources such as `webhooks.clerk()` and `webhooks.openai()` select the corresponding configuration. ## Named providers diff --git a/docs/webhooks/webhook-tasks.mdx b/docs/webhooks/webhook-tasks.mdx index 95062ef0540..cba8f7425ff 100644 --- a/docs/webhooks/webhook-tasks.mdx +++ b/docs/webhooks/webhook-tasks.mdx @@ -1,10 +1,10 @@ --- title: "Webhook tasks" sidebarTitle: "Webhook tasks" -description: "What a webhook() handler receives, the task options it takes, how to order deliveries per customer, and the options an endpoint takes." +description: "What a webhook() handler receives, the task options it takes, how to group deliveries per customer, and the options an endpoint takes." --- -**A webhook task is a [task](/tasks/overview) with an endpoint attached: `webhook()` runs `onEvent` once for each delivery that passes its [filter](/webhooks/filters).** +**A webhook task is a [task](/tasks/overview) with an endpoint attached: `webhook()` starts a task run for each delivery that passes its [filter](/webhooks/filters).** If an attempt fails, the run retries and calls `onEvent` again, so keep its side effects safe to repeat. ## Handler arguments @@ -13,7 +13,7 @@ description: "What a webhook() handler receives, the task options it takes, how | Argument | Value | | --- | --- | | `event` | The verified request body, parsed as JSON. Its TypeScript type comes from the [source](/webhooks/verification#typing-the-event). | -| `headers` | Request headers as a Web `Headers` object, with case-insensitive `get()` and `has()` methods. `authorization`, `proxy-authorization`, `cookie`, `set-cookie` and shared-secret headers are removed; signature headers such as `stripe-signature` are kept. Stored headers are capped at 4 KB. | +| `headers` | Request headers as a Web `Headers` object, with case-insensitive `get()` and `has()` methods. `authorization`, `proxy-authorization`, `cookie`, `set-cookie` and shared-secret headers are removed; other headers, including signature headers such as `stripe-signature`, share a 4 KB budget, so a large set of headers can drop some. Headers a live waiter matches on are always kept. | | `endpoint` | The endpoint the delivery arrived on: `id`, `declaredId`, `tenantId`, `externalRef`, and the `metadata` you declared. | | `ctx` | The same [run context](/context) that regular tasks receive. | @@ -37,9 +37,9 @@ export const orders = webhook({ }); ``` -## Ordering per customer +## Group deliveries per customer -The limit covers every delivery the task handles. To process each customer's events in order while different customers run in parallel, route them to an agent with [session routing](/webhooks/session-routing): deliveries with the same key land in one session and are handled one after another. +The limit covers every delivery the task handles. To group each customer's events while different customers run in parallel, route them to an agent with [session routing](/webhooks/session-routing): deliveries with the same key land in one session and are handled one at a time. A retried delivery can reach the session after a later one, so don't rely on arrival order. ## Endpoint options From 9f1576dc012ee4055c2565bcd85992afd815686c Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Fri, 13 Nov 2026 16:50:48 +0000 Subject: [PATCH 36/37] docs: harden the Hookdeck trigger API example Send the wrapped body as JSON, accept any payload type, and require authentication on the Hookdeck source. --- docs/webhooks/providers/hookdeck.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/webhooks/providers/hookdeck.mdx b/docs/webhooks/providers/hookdeck.mdx index 98d475ca2e8..5cdc7b23aa1 100644 --- a/docs/webhooks/providers/hookdeck.mdx +++ b/docs/webhooks/providers/hookdeck.mdx @@ -77,18 +77,19 @@ You can also point a Hookdeck destination at the [trigger task API](/management/ ```javascript addHandler("transform", (request, context) => { request.body = { payload: request.body }; + request.headers["content-type"] = "application/json"; return request; }); ``` -3. Create a connection from your source to that destination and transformation. +3. Create a connection from your source to that destination and transformation. Turn on authentication for the Hookdeck source, such as the provider's signature verification: the destination's API key only authenticates Hookdeck to Trigger.dev, so an unauthenticated source would forward anyone's requests. ```ts /trigger/webhook-handler.ts import { task } from "@trigger.dev/sdk"; export const webhookHandler = task({ id: "webhook-handler", - run: async (payload: Record) => { + run: async (payload: unknown) => { console.log("Received webhook:", payload); }, }); From 1ade15acc20f168b5f3b40004b8f7f06eccccb20 Mon Sep 17 00:00:00 2001 From: Jack Bridger Date: Mon, 16 Nov 2026 10:37:01 +0000 Subject: [PATCH 37/37] docs: restore Brex, Composio and Intercom webhook provider pages Bring the three pages back now that their verification and URL checks are fixed: Brex reads the Standard Webhooks headers, Composio keys the signature with the raw secret, and endpoints answer Intercom's HEAD check. --- docs/docs.json | 15 ++-------- docs/webhooks/deliveries.mdx | 4 +-- docs/webhooks/providers.mdx | 3 ++ docs/webhooks/providers/brex.mdx | 45 ++++++++++++++++++++++++++++ docs/webhooks/providers/composio.mdx | 45 ++++++++++++++++++++++++++++ docs/webhooks/providers/intercom.mdx | 41 +++++++++++++++++++++++++ 6 files changed, 139 insertions(+), 14 deletions(-) create mode 100644 docs/webhooks/providers/brex.mdx create mode 100644 docs/webhooks/providers/composio.mdx create mode 100644 docs/webhooks/providers/intercom.mdx diff --git a/docs/docs.json b/docs/docs.json index ff90f748016..cd577c93c2e 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -193,9 +193,11 @@ "webhooks/providers", "webhooks/providers/attio", "webhooks/providers/autumn", + "webhooks/providers/brex", "webhooks/providers/cal-com", "webhooks/providers/calendly", "webhooks/providers/clerk", + "webhooks/providers/composio", "webhooks/providers/discord", "webhooks/providers/docusign", "webhooks/providers/elevenlabs", @@ -205,6 +207,7 @@ "webhooks/providers/granola", "webhooks/providers/hookdeck", "webhooks/providers/infisical", + "webhooks/providers/intercom", "webhooks/providers/jira", "webhooks/providers/langfuse", "webhooks/providers/linear", @@ -897,18 +900,6 @@ "source": "/webhooks/providers/notion", "destination": "/webhooks/providers" }, - { - "source": "/webhooks/providers/brex", - "destination": "/webhooks/providers" - }, - { - "source": "/webhooks/providers/intercom", - "destination": "/webhooks/providers" - }, - { - "source": "/webhooks/providers/composio", - "destination": "/webhooks/providers" - }, { "source": "/webhooks/providers/zoom", "destination": "/webhooks/providers" diff --git a/docs/webhooks/deliveries.mdx b/docs/webhooks/deliveries.mdx index e9d12b47426..6ed79a427dd 100644 --- a/docs/webhooks/deliveries.mdx +++ b/docs/webhooks/deliveries.mdx @@ -89,8 +89,8 @@ When the source maps a provider event ID, that ID becomes the key, so the provid | Key | Providers | | --- | --- | -| A header | GitHub (`X-GitHub-Delivery`); Svix, Clerk, Resend and Autumn (`svix-id`); Standard Webhooks, OpenAI, Replicate, Recall.ai, Loops and Granola (`webhook-id`); Linear (`Linear-Delivery`); PagerDuty (`X-Webhook-Id`); Jira (`X-Atlassian-Webhook-Identifier`); Zendesk (`X-Zendesk-Webhook-Invocation-Id`); Attio (`Idempotency-Key`); Shopify (`X-Shopify-Webhook-Id`); Hookdeck (`X-Hookdeck-Eventid`, or `-eventid` with a custom header prefix) | -| A body field | Stripe, Vercel, WorkOS, Metronome, Mux, Langfuse and Plain (`id`); Square, Slack and Typeform (`event_id`); Firecrawl (`webhookId`) | +| A header | GitHub (`X-GitHub-Delivery`); Svix, Clerk, Resend and Autumn (`svix-id`); Standard Webhooks, Brex, Composio, OpenAI, Replicate, Recall.ai, Loops and Granola (`webhook-id`); Linear (`Linear-Delivery`); PagerDuty (`X-Webhook-Id`); Jira (`X-Atlassian-Webhook-Identifier`); Zendesk (`X-Zendesk-Webhook-Invocation-Id`); Attio (`Idempotency-Key`); Shopify (`X-Shopify-Webhook-Id`); Hookdeck (`X-Hookdeck-Eventid`, or `-eventid` with a custom header prefix) | +| A body field | Stripe, Vercel, Intercom, WorkOS, Metronome, Mux, Langfuse and Plain (`id`); Square, Slack and Typeform (`event_id`); Firecrawl (`webhookId`) | The other built-in providers (Calendly, Cal.com, Sentry, DocuSign, ElevenLabs, Vapi, Retell, Tailscale, Infisical, PlanetScale, Supabase, Discord, GitLab and WhatsApp) use the fallback below. diff --git a/docs/webhooks/providers.mdx b/docs/webhooks/providers.mdx index f325d06f74a..16cd5d2ba2d 100644 --- a/docs/webhooks/providers.mdx +++ b/docs/webhooks/providers.mdx @@ -10,9 +10,11 @@ description: "Every built-in webhook provider, with its SDK function, the creden | --- | --- | --- | | [Attio](/webhooks/providers/attio) | `webhooks.attio()` | Issued by the provider | | [Autumn](/webhooks/providers/autumn) | `webhooks.autumn()` | Issued by the provider | +| [Brex](/webhooks/providers/brex) | `webhooks.brex()` | Issued by the provider | | [Cal.com](/webhooks/providers/cal-com) | `webhooks.calCom()` | You generate it | | [Calendly](/webhooks/providers/calendly) | `webhooks.calendly()` | You choose it (OAuth apps: issued by the provider) | | [Clerk](/webhooks/providers/clerk) | `webhooks.clerk()` | Issued by the provider | +| [Composio](/webhooks/providers/composio) | `webhooks.composio()` | Issued by the provider | | [Discord](/webhooks/providers/discord) | `webhooks.discord()` | Provider's public key | | [DocuSign](/webhooks/providers/docusign) | `webhooks.docusign()` | Issued by the provider | | [ElevenLabs](/webhooks/providers/elevenlabs) | `webhooks.elevenlabs()` | Issued by the provider | @@ -22,6 +24,7 @@ description: "Every built-in webhook provider, with its SDK function, the creden | [Granola](/webhooks/providers/granola) | `webhooks.granola()` | Issued by the provider | | [Hookdeck](/webhooks/providers/hookdeck) | `webhooks.hookdeck()` | Issued by the provider | | [Infisical](/webhooks/providers/infisical) | `webhooks.infisical()` | You generate it | +| [Intercom](/webhooks/providers/intercom) | `webhooks.intercom()` | Issued by the provider | | [Jira](/webhooks/providers/jira) | `webhooks.jira()` | You generate it | | [Langfuse](/webhooks/providers/langfuse) | `webhooks.langfuse()` | Issued by the provider | | [Linear](/webhooks/providers/linear) | `webhooks.linear()` | Issued by the provider | diff --git a/docs/webhooks/providers/brex.mdx b/docs/webhooks/providers/brex.mdx new file mode 100644 index 00000000000..2a39a12799d --- /dev/null +++ b/docs/webhooks/providers/brex.mdx @@ -0,0 +1,45 @@ +--- +title: "Brex webhooks" +sidebarTitle: "Brex" +description: "Receive and verify Brex webhooks with Trigger.dev. Check the Standard Webhooks signature and run a task for each Brex event, filtered on event.event_type." +--- + +**`webhooks.brex()` verifies the Standard Webhooks signature Brex sends in the `webhook-*` headers on every request.** + + + Brex verification needs `@trigger.dev/sdk` 4.8.6 or later. Redeploy existing endpoints after upgrading. + + +```ts /trigger/brex.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const brex = webhooks.endpoint.define({ + id: "brex", + source: webhooks.brex(), +}); + +export const brexEvents = webhook({ + id: "brex-events", + endpoint: brex, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.event_type`. + +| Setting | Value | +| --- | --- | +| Source | `webhooks.brex()` | +| Verification | Standard Webhooks (`webhook-id`, `webhook-timestamp`, `webhook-signature`) | +| Credential | Signing secret from `GET /v1/webhooks/secrets` | +| Event type | `event.event_type` | +| Brex docs | [Brex webhook docs](https://developer.brex.com/guides/webhooks) | + +## Set up Brex + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Brex has no webhook settings page. Register the webhook URL with `POST /v1/webhooks`, passing `url` and the `event_types` your subscribers need. Brex allows one webhook endpoint per customer. +3. Get the signing secret from `GET /v1/webhooks/secrets`, then choose **Set signing secret** on the Trigger.dev endpoint and paste it. The secret has no `whsec_` prefix. During a key rotation the call returns two secrets; use the new one. +4. Send a test event from Brex, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/composio.mdx b/docs/webhooks/providers/composio.mdx new file mode 100644 index 00000000000..f47e0c91491 --- /dev/null +++ b/docs/webhooks/providers/composio.mdx @@ -0,0 +1,45 @@ +--- +title: "Composio webhooks" +sidebarTitle: "Composio" +description: "Receive and verify Composio webhooks with Trigger.dev. Check the signature in the webhook-signature header and run a task for each Composio event, filtered on event.type." +--- + +**`webhooks.composio()` verifies the signature Composio sends in the `webhook-*` headers on every request, keyed with the secret's raw text as Composio signs it.** + + + Composio verification needs `@trigger.dev/sdk` 4.8.6 or later. Redeploy existing endpoints after upgrading. + + +```ts /trigger/composio.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const composio = webhooks.endpoint.define({ + id: "composio", + source: webhooks.composio(), +}); + +export const composioEvents = webhook({ + id: "composio-events", + endpoint: composio, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.type`. + +| Setting | Value | +| --- | --- | +| Source | `webhooks.composio()` | +| Verification | Standard Webhooks headers (`webhook-id`, `webhook-timestamp`, `webhook-signature`), keyed with the secret's raw text | +| Credential | Signing secret issued by Composio | +| Event type | `event.type`, which is `composio.trigger.message` for trigger events | +| Composio docs | [Composio webhook docs](https://docs.composio.dev/docs/setting-up-triggers/subscribing-to-events) | + +## Set up Composio + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Register the webhook URL for your Composio project with `composio.triggers.setWebhookSubscription({ webhookUrl })` in the Composio SDK (`set_webhook_subscription` in Python). Composio then sends every trigger event in the project to it. +3. The subscription's response includes its `secret`. Copy it, then choose **Set signing secret** on the Trigger.dev endpoint. You can read or rotate it later through the SDK's webhook subscriptions methods. +4. Send a test event from Composio, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives. diff --git a/docs/webhooks/providers/intercom.mdx b/docs/webhooks/providers/intercom.mdx new file mode 100644 index 00000000000..764d34412b0 --- /dev/null +++ b/docs/webhooks/providers/intercom.mdx @@ -0,0 +1,41 @@ +--- +title: "Intercom webhooks" +sidebarTitle: "Intercom" +description: "Receive and verify Intercom webhooks with Trigger.dev. Check the HMAC-SHA1 signature in x-hub-signature and run a task for each Intercom event, filtered on event.topic." +--- + +**`webhooks.intercom()` verifies the HMAC-SHA1 signature Intercom sends in `x-hub-signature` on every request.** + +```ts /trigger/intercom.ts +import { webhook, webhooks } from "@trigger.dev/sdk"; + +export const intercom = webhooks.endpoint.define({ + id: "intercom", + source: webhooks.intercom(), +}); + +export const intercomEvents = webhook({ + id: "intercom-events", + endpoint: intercom, + onEvent: async ({ event }) => { + console.log(event); + }, +}); +``` + +To run a subscriber only for some events, add a [filter](/webhooks/filters) on `event.topic`. + +| Setting | Value | +| --- | --- | +| Source | `webhooks.intercom()` | +| Verification | HMAC-SHA1 in `x-hub-signature` | +| Credential | Your Intercom app's client secret | +| Event type | `event.topic` | +| Intercom docs | [Intercom webhook docs](https://developers.intercom.com/docs/references/webhooks/webhook-models) | + +## Set up Intercom + +1. Start `trigger dev` or deploy, then copy the endpoint's **Webhook URL** from the **Webhooks** page. +2. Intercom signs webhooks with your app's client secret. In the Intercom Developer Hub, open your app, copy the **Client secret** from **Basic information**, and choose **Set signing secret** on the Trigger.dev endpoint. +3. Open **Configure > Webhooks**, enter the webhook URL as the endpoint URL and select the topics your subscribers need. Intercom checks the URL with a HEAD request, which the endpoint answers. +4. Send a test event from Intercom, or use the endpoint's **Test** tab, and check the endpoint's **Deliveries** tab. See [Verify the connection](/webhooks/connect#verify-the-connection) if nothing arrives.