---
title: "Create Webhook"
method: POST
path: "/v1/webhooks"
tags: ["Webhooks"]
---

# Create Webhook

`POST /v1/webhooks`

## Request

- Base URL: `https://api.anchorbrowser.io`
- URL: `https://api.anchorbrowser.io/v1/webhooks`
- Auth: API key in header `anchor-api-key`

Register a new HTTPS endpoint to receive events. The response includes
a one-time `secret` (HMAC-SHA256 signing key) — store it; Anchor never
returns it again. Up to 5 webhooks per project.

## Request body

- WebhookCreateRequest
  - `url` string, uri, required: HTTPS endpoint Anchor will POST events to. Rejected (400) if it points at loopback / private / link-local IPs, cloud metadata services, internal-only TLDs, AWS STS / IAM / EKS endpoints, or contains basic-auth credentials.
  - `description` string: Optional human-readable description.
  - `subscribed_events` WebhookEventType[], required: Events this webhook should receive. At least one is required.

## Response `201`

Webhook created. The `secret` field is returned ONCE — copy it now.

- WebhookWithSecret: A registered webhook subscription. The signing secret is NEVER returned by GET/list endpoints.
  - `id` string, required: Webhook id. Use as the path parameter on subsequent calls.
  - `project_id` string, uuid, required: The project (team) the webhook belongs to.
  - `url` string, uri, required: HTTPS URL Anchor will POST events to.
  - `description` string, nullable, required: Optional human-readable description.
  - `subscribed_events` WebhookEventType[], required: Event types this webhook is currently subscribed to.
  - `enabled` boolean, required: When `false`, no events fan out to this webhook.
  - `created_at` string, date-time, nullable, required
  - `updated_at` string, date-time, nullable, required
  - `secret` string, required: HMAC-SHA256 signing secret. Use this to verify the `Anchor-Signature` header on each delivery.

## Other responses

- `400`: Validation error. Common causes — non-HTTPS URL, URL targets a private/loopback IP, cloud metadata service, internal-only TLD (`*.local`/`*.internal`), AWS STS/IAM/EKS endpoint, contains basic-auth credentials, exceeds 2048 chars, or `subscribed_events` is empty.
- `409`: Per-project webhook limit (5) reached. Delete or reuse an existing webhook.
- `500`: Failed to create webhook.

## Changes

- **2026-10-16** `b3bfdb98c79e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/anchorbrowser/apis/anchorbrowser-api/changes/v1/webhooks/post.md)

---

[API](https://skmtc.dev/anchorbrowser/apis/anchorbrowser-api.md) - [All operations](https://skmtc.dev/anchorbrowser/apis/anchorbrowser-api/llms.txt) - [OpenAPI document](https://skmtc.dev/anchorbrowser/apis/anchorbrowser-api/revisions/9d755f22df0e?raw)