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

# Create webhook

`POST /api/webhooks`

## Request

- Base URL: `https://api.zvid.io`
- URL: `https://api.zvid.io/api/webhooks`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Register an account endpoint. Registered deliveries are signed with HMAC-SHA256(secret, timestamp + "." + raw body). There are at most 5 total attempts (initial plus retries after 30, 60, 120 and 240 seconds), a 10-second HTTP timeout, and no redirect following. Endpoints are disabled after 20 consecutive exhausted deliveries. Creation and GET by ID return the signing secret.

## Request body

- WebhookRequest
  - `url` string, uri, required
  - `description` string
  - `events` string[]

## Response `201`

Webhook created (includes secret)

- Webhook
  - `id` string, required
  - `url` string, required
  - `description` string
  - `events` string[], required
  - `status` 'active' | 'disabled', required
  - `secret` string: Returned by creation and single-webhook lookup; omitted from list/update responses.
  - `consecutiveFailures` integer
  - `lastSuccessAt` string, nullable
  - `lastFailureAt` string, nullable
  - `lastFailureReason` string, nullable
  - `createdAt` string
  - `updatedAt` string

## Other responses

- `400`: Invalid URL (the hosted API requires a public HTTPS address and rejects private hosts)
- `401`: Unauthorized

---

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