Webhooks overview

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.

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.

webhook() also takes the options a task does, such as queue, concurrency, machine, retry, maxDuration and the lifecycle hooks. For example, to handle one delivery at a time:

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: 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.

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. 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 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.

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

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.

Getting started

Fundamentals

Building with AI

Writing tasks

Agents

Webhooks

Configuration

Deployment

Private networking

Realtime

CLI

Observability

Using the Dashboard

Troubleshooting

Self-hosting

Open source

Help

The handler

How it works

Pricing and limits

Connect it

Connect a provider

Sources and verification

Filters

Waiters

Deliveries and endpoints

Session routing

Channels

Human-in-the-loop

​What can subscribe

​The handler

​How it works

​Pricing and limits

​Connect it

Connect a provider

Sources and verification

Filters

Waiters

Deliveries and endpoints

Session routing

Channels

Human-in-the-loop

What can subscribe

The handler

How it works

Pricing and limits

Connect it