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

# Create a webhook

`POST /v1/webhooks`

## Request

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

Registers a new webhook endpoint. Chronary will deliver signed POST requests to your URL when subscribed events occur. The signing secret is returned only at creation time — store it securely.

## Request body

- CreateWebhook
  - `url` string, uri, required
  - `events` string[], required

## Response `201`

Webhook created

- WebhookCreated
  - `id` string, required
  - `orgId` string, required
  - `url` string, uri, required
  - `events` string[], required
  - `active` boolean, required
  - `consecutiveFailures` integer, required: Circuit-breaker counter: consecutive terminal delivery failures. Reset to 0 on any successful delivery; the endpoint is auto-deactivated at 20 or after 24h of continuous failure.
  - `firstFailureAt` string, date-time, nullable, required: Timestamp of the first failure in the current failure streak; null when there is no active streak.
  - `createdAt` string, date-time, required
  - `secret` string, required: HMAC-SHA256 signing secret — returned once at creation time only. Store it securely.

## Other responses

- `400`: Validation error — invalid request body or query parameters
- `401`: Unauthorized — missing or invalid API key
- `403`: Forbidden — quota exceeded or operation not permitted
- `429`: Rate limited — 10 requests per second per key exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/chronary/apis/chronary-api.md) · [All operations](https://skmtc.dev/chronary/apis/chronary-api/llms.txt) · [OpenAPI document](https://skmtc.dev/chronary/apis/chronary-api/revisions/0d1a330294ae?raw)