---
title: "Create a webhook waiter"
method: POST
path: "/api/v1/webhooks/endpoints/{endpointId}/waiters"
tags: ["webhooks"]
---

# Create a webhook waiter

`POST /api/v1/webhooks/endpoints/{endpointId}/waiters`

## Request

- Base URL: `https://api.trigger.dev`
- URL: `https://api.trigger.dev/api/v1/webhooks/endpoints/{endpointId}/waiters`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/docs/api/v1/webhooks/endpoints/:endpointId/waiters/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a waiter on an endpoint. A waiter is a waitpoint that completes when a matching delivery arrives on the endpoint, so a run waiting on its id resumes with the verified event. It only matches deliveries that arrive after it was created. Omit `match` to get a waiter with its own `url`, for providers that take a webhook URL per request.

## Request body

- CreateWebhookWaiterRequest
  - `match` object: Up to five paths, each mapped to the value it must equal. `event.*` reads the event body, `header.*` a request header (case-insensitive) and `webhook.*` the endpoint (`id`, `source`, `externalRef`, `tenantId` or `deliveryId`). Omit it to create a waiter with its own `url`.
  - `filter` string: A [filter](/webhooks/filters) the event must also pass, checked after `match`.
  - `timeout` string: A duration such as `30m` or `1h`, or an ISO 8601 date. Defaults to 24 hours, up to 90 days.
  - `tags` union: Up to 10 tags, added to the `webhook:<endpoint id>` tag every waiter gets.
    - string
    - string[]
  - `idempotencyKey` string: A create with a key already used in the environment returns the original waiter with `isCached: true`, even if it has completed.
  - `idempotencyKeyTTL` string: How long the idempotency key lasts, such as `1h` or `30d`.

## Response `200`

Waiter created, or the existing waiter for this idempotency key

- CreateWebhookWaiterResponse
  - `id` string, required: The waiter's id, which is also its waitpoint id. Wait on it with `webhooks.waiter.wait()` or `wait.forToken()`.
  - `url` string: Only for a waiter created without `match`: the URL to give the provider as its per-request webhook. A delivery to it is verified with the endpoint's source and resumes only this waiter.
  - `expiresAt` string, date-time, required: When the waiter times out.
  - `isCached` boolean, required: `true` if an existing waiter was returned for the same `idempotencyKey`.

## Other responses

- `401`: Unauthorized request
- `404`: No active endpoint with this id in the environment's current deployment
- `422`: A limit was reached (`webhook_waiter_limit`), the filter doesn't parse (`webhook_filter_invalid`), or the request is invalid (`invalid_request`), for example an unknown `match` path or a bad `timeout`

## Changes

- **2026-10-15** `f44b1ec886c8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/changes/api/v1/webhooks/endpoints/:endpointId/waiters/post.md)

---

[API](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api.md) - [All operations](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/revisions/441161111493?raw)