Create webhook

POST /api/webhooks

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.

Authentication

• Option 1: x-api-key: YOUR_API_KEY (header). API key for authentication. Create one in your dashboard.
• Option 2: Authorization: Bearer YOUR_ACCESS_TOKEN. Dashboard JWT in Authorization: Bearer <token>, only on operations that explicitly list this scheme. Prefer x-api-key for REST integrations. OAuth for hosted MCP is a separate connection at https://mcp.zvid.io/mcp.

Create API keys at app.zvid.io/api-keys. Keep credentials on your server.

Parameters

This operation has no path, query, or additional header parameters.

Request

The shell examples read credentials from ZVID_API_KEY (or ZVID_ACCESS_TOKEN for Bearer authentication). Set that variable in your environment. Replace sample project, template, job, and asset identifiers with values from your own account.

A request body is required.

application/json

Unknown properties are rejected. Required properties: url.

Field	Type	Required	Description and constraints
body.url	string	Yes	Maximum length: 2048. Format: uri.
body.description	string	No	Maximum length: 255.
body.events	array of "render.completed" / "render.failed"	No	Minimum items: 1. Items must be unique.

Nested field: body.events

Minimum items: 1. Items must be unique.

Array item: body.events[]

Type: "render.completed" / "render.failed".

Request example: endpoint

curl --request POST 'https://api.zvid.io/api/webhooks' \
  --header "x-api-key: $ZVID_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://example.com/hooks/zvid",
  "events": [
    "render.completed",
    "render.failed"
  ]
}'

Responses

HTTP 201

Webhook created (includes secret)

Content type: application/json.

Required properties: id, url, events, status.

Field	Type	Required	Description and constraints
response.id	string	Yes
response.url	string	Yes
response.description	string	No
response.events	array of "render.completed" / "render.failed"	Yes
response.status	"active" / "disabled"	Yes
response.secret	string	No	Returned by creation and single-webhook lookup; omitted from list/update responses.
response.consecutiveFailures	integer	No
response.lastSuccessAt	string OR null	No	At least one listed alternative must match.
response.lastFailureAt	string OR null	No	At least one listed alternative must match.
response.lastFailureReason	string OR null	No	At least one listed alternative must match.
response.createdAt	string	No
response.updatedAt	string	No

Nested field: response.events

Array item: response.events[]

Type: "render.completed" / "render.failed".

Nested field: response.lastSuccessAt

At least one listed alternative must match.

anyOf alternative 1

Type: string.

anyOf alternative 2

Type: null.

Nested field: response.lastFailureAt

At least one listed alternative must match.

anyOf alternative 1

Type: string.

anyOf alternative 2

Type: null.

Nested field: response.lastFailureReason

At least one listed alternative must match.

anyOf alternative 1

Type: string.

anyOf alternative 2

Type: null.

Representative successful response response

{
  "id": "whk_abcdefghijklmnopqrst",
  "url": "https://example.com/hooks/zvid",
  "events": [
    "render.completed"
  ],
  "status": "active",
  "secret": "whsec_example_not_a_real_secret",
  "created": true
}

HTTP 400

Invalid URL (the hosted API requires a public HTTPS address and rejects private hosts)

Content type: application/json.

Required properties: error.

Field	Type	Required	Description and constraints
response.error	string	Yes
response.message	string	No
response.details	array of object	No
response.planLimits	object	No	Present on render validation errors; contains the authenticated user's current render limits.

Nested field: response.details

Array item: response.details[]

Unknown properties are rejected. Required properties: field, message.

Field	Type	Required	Description and constraints
response.details[].field	string	Yes
response.details[].message	string	Yes

HTTP 401

Unauthorized

Content type: application/json.

Unknown properties are rejected. Required properties: error.

Field	Type	Required	Description and constraints
response.error	string	Yes	Error type
response.message	string	No	Human-readable error message

Schema definitions

The following definitions describe the fields referenced above. Expand a definition to inspect its complete contract.

WebhookRequest

Unknown properties are rejected. Required properties: url.

Field	Type	Required	Description and constraints
WebhookRequest.url	string	Yes	Maximum length: 2048. Format: uri.
WebhookRequest.description	string	No	Maximum length: 255.
WebhookRequest.events	array of "render.completed" / "render.failed"	No	Minimum items: 1. Items must be unique.

Nested field: WebhookRequest.events

Minimum items: 1. Items must be unique.

Array item: WebhookRequest.events[]

Type: "render.completed" / "render.failed".

Webhook

Required properties: id, url, events, status.

Field	Type	Required	Description and constraints
Webhook.id	string	Yes
Webhook.url	string	Yes
Webhook.description	string	No
Webhook.events	array of "render.completed" / "render.failed"	Yes
Webhook.status	"active" / "disabled"	Yes
Webhook.secret	string	No	Returned by creation and single-webhook lookup; omitted from list/update responses.
Webhook.consecutiveFailures	integer	No
Webhook.lastSuccessAt	string OR null	No	At least one listed alternative must match.
Webhook.lastFailureAt	string OR null	No	At least one listed alternative must match.
Webhook.lastFailureReason	string OR null	No	At least one listed alternative must match.
Webhook.createdAt	string	No
Webhook.updatedAt	string	No

Nested field: Webhook.events

Array item: Webhook.events[]

Type: "render.completed" / "render.failed".

Nested field: Webhook.lastSuccessAt

At least one listed alternative must match.

anyOf alternative 1

Type: string.

anyOf alternative 2

Type: null.

Nested field: Webhook.lastFailureAt

At least one listed alternative must match.

anyOf alternative 1

Type: string.

anyOf alternative 2

Type: null.

Nested field: Webhook.lastFailureReason

At least one listed alternative must match.

anyOf alternative 1

Type: string.

anyOf alternative 2

Type: null.

ValidationError

Required properties: error.

Field	Type	Required	Description and constraints
ValidationError.error	string	Yes
ValidationError.message	string	No
ValidationError.details	array of object	No
ValidationError.planLimits	object	No	Present on render validation errors; contains the authenticated user's current render limits.

Nested field: ValidationError.details

Array item: ValidationError.details[]

Unknown properties are rejected. Required properties: field, message.

Field	Type	Required	Description and constraints
ValidationError.details[].field	string	Yes
ValidationError.details[].message	string	Yes

AuthenticationError

Unknown properties are rejected. Required properties: error.

Field	Type	Required	Description and constraints
AuthenticationError.error	string	Yes	Error type
AuthenticationError.message	string	No	Human-readable error message

Related resources

• OpenAPI specification
• Project payload schema
• Quick Start
• Authentication guide