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

# Register a webhook endpoint

`POST /v1/webhooks`

## Request

- Base URL: `https://api.vivideo.ai`
- URL: `https://api.vivideo.ai/v1/webhooks`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/vivideo/apis/vivideo-api/docs/v1/webhooks/post.ts> (a function with typed inputs; its response is checked against the schema)

Registers a public **https** URL for `video.completed` / `video.failed`
events. The response includes the signing `secret` (shown once). Verify
deliveries via the `Vivideo-Signature: t=<ts>,v1=<hmac>` header, where
`v1 = hex(hmac_sha256(secret, "<ts>.<raw body>"))`. Deliveries retry
with backoff (1m, 5m, 30m, 2h, 6h); dedupe on the event `id`. Max 5
active endpoints per account.

## Request body

- object
  - `url` string, required
  - `events` string[]

## Response `201`

Endpoint registered — store the secret now.

- WebhookEndpoint
  - `id` string
  - `object` string
  - `url` string
  - `events` string[]
  - `status` string
  - `created_at` integer
  - `secret` string: Signing secret (whsec_...) — returned ONLY at creation.

## Other responses

- `400`: Invalid parameters (`invalid_request`, `unknown_model`, `invalid_url`).
- `401`: Missing, malformed or revoked API key (`missing_api_key`, `invalid_api_key`, `api_key_revoked`).
- `429`: Rate limit hit (`rate_limited`). Honor the `Retry-After` header / `retry_after_seconds` field.

---

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