v1

latestOpenAPI 3.1.02026-07-2665164286.3 KB

Webhooks

Create Webhook Endpoint

Registers an HTTPS URL to receive webhook event notifications. Returns the endpoint details and a signing secret. The signing secret is only shown at creation and rotation — store it securely.

post/v3/webhooks/endpoints

Headers

Idempotency-Keystring

Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent.

Request body

urlstring required

Publicly accessible HTTPS URL that will receive webhook POST requests.

eventsWebhookEventType[] nullable

Event types to subscribe to. Omit or set to null to receive all events.

entity_idstring nullable

Optional entity ID to scope this endpoint to a specific resource (e.g. a personalized video project).

Response

Successful response

Example response

{
  "data": {
    "endpoint_id": "ep_abc123def456",
    "url": "https://example.com/webhook",
    "events": [
      "avatar_video.success",
      "avatar_video.fail"
    ],
    "status": "enabled",
    "created_at": "2024-04-01T12:00:00Z",
    "secret": "whsec_abc123def456"
  }
}