---
title: "Create a webhook endpoint (team-scoped)"
method: POST
path: "/v1/webhooks"
tags: ["Webhooks"]
---

# Create a webhook endpoint (team-scoped)

`POST /v1/webhooks`

## Request

- Base URL: `https://api.virlo.ai`
- URL: `https://api.virlo.ai/v1/webhooks`
- Auth: HTTP bearer

## Request body

- CreateWebhookDto
  - `url` string, required: HTTPS destination URL
  - `description` string
  - `enabled_events` string[], required: Event types this endpoint should receive
  - `headers` object: Up to 5 custom headers to include on every delivery (e.g. Authorization: Bearer …)
  - `is_active` boolean

## Response `201`

Webhook endpoint created

- WebhookEndpointDto
  - `id` string, uuid, required
  - `team_id` string, uuid, required
  - `url` string, required
  - `description` string, nullable
  - `enabled_events` string[], required
  - `headers` object: Custom headers included on every delivery (secrets redacted in docs examples).
  - `is_active` boolean, required
  - `status` 'active' | 'inactive' | 'disabled_by_system', required: Effective status: `inactive` when soft-deleted (`is_active=false`), `disabled_by_system` when the circuit breaker tripped, otherwise `active`.
  - `consecutive_failures` number, required
  - `last_success_at` string, nullable
  - `last_failure_at` string, nullable
  - `created_by` string, uuid, nullable
  - `created_at` string, required
  - `updated_at` string, required

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key (`missing_api_key` / `invalid_api_key`)
- `409`: Active endpoint quota exceeded
- `429`: Rate limit exceeded (`rate_limit_exceeded`); see the Retry-After header

---

[API](https://skmtc.dev/virlo/apis/virlo-public-api.md) · [All operations](https://skmtc.dev/virlo/apis/virlo-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/virlo/apis/virlo-public-api/revisions/3b69c6145087?raw)