Webhooks overview

Receive provider webhooks on hosted, verified endpoints and route each event to tasks, agents, and waiting runs.

Private beta. This feature is only available to some organizations right now.

Request access and we’ll turn webhooks on for your organization and send you the prerelease packages. Webhooks are open source, so they work self-hosted too. APIs may change before general availability.

A webhook endpoint is one hosted URL that you register with a provider. Trigger.dev verifies every request against the endpoint’s source, records it as a delivery, and hands the event to everything subscribed to the endpoint.

Declare the endpoint once, then subscribe to it:

/trigger/stripe.ts

import { webhook, webhooks } from "@trigger.dev/sdk";

export const stripe = webhooks.endpoint.define({
  id: "stripe",
  source: webhooks.stripe(),
});

export const fulfillOrder = webhook({
  id: "fulfill-order",
  endpoint: stripe,
  filter: "event.type == 'checkout.session.completed'",
  onEvent: async ({ event }) => {
    console.log("Fulfilling", event.data.object.id);
  },
});

export const recordRefund = webhook({
  id: "record-refund",
  endpoint: stripe,
  filter: "event.type == 'charge.refunded'",
  onEvent: async ({ event, headers, endpoint, ctx }) => {
    console.log("Refund", event.id, "on", endpoint?.id, "in run", ctx.run.id);
  },
});

Stripe gets one URL. A checkout event runs fulfill-order, a refund runs record-refund, and anything else is recorded as FILTERED.

What can subscribe

Subscriber	Declared with	What a delivery does
Task	webhook({ endpoint, onEvent })	Starts a run of the task with the event.
Agent session	chat.event({ endpoint, key }) listed on a chat.agent	Delivers an action to the session the key names.
Chat frontend	a channel connector 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 })	Resumes a run that is waiting for this event.

Each subscriber has its own filter, 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.
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 that regular tasks receive.

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.

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.

Connect a provider

Register the URL and signing secret, then send a test event.

Sources and verification

Choose a provider source or define a custom verification scheme.

Filters

Choose which events reach each subscriber.

Waiters

Pause a run until a matching webhook arrives.

Deliveries and endpoints

Inspect received events and where each one went.

Session routing

Route deliveries to a durable per-key agent session.

Channels

Turn a webhook into a chat frontend for an agent.

Human-in-the-loop

Approvals and interactive controls over a channel.