Webhooks

Create a webhook

Register an HTTPS endpoint to be told when a run finishes or a draft is ready. The signing secret is returned once and never again.

POSThttps://api.vidrys.com/v1/webhooks

Plan: Custom
Key: read-and-write
Rate cost: 1 unit

The URL must be HTTPS and publicly resolvable — private and internal addresses are refused, and checked again on every delivery.

Up to 10 webhooks per workspace. See Webhooks for the signature, the retry schedule and the payloads.

Create a webhook

curl --request POST \
  --url "https://api.vidrys.com/v1/webhooks" \
  --header "Authorization: Bearer $VIDRYS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "url": "https://hooks.acmeinvoicing.com/vidrys",
  "events": [
    "run.completed",
    "draft.ready"
  ]
}'

201 · success

{
  "webhook": {
    "id": "9a8b7c6d-5e4f-4a3b-82c1-0d9e8f7a6b5c",
    "url": "https://hooks.acmeinvoicing.com/vidrys",
    "events": [
      "run.completed",
      "draft.ready"
    ],
    "is_active": true,
    "last_status": 200,
    "last_delivery_at": "2026-09-21T04:02:19Z",
    "created_at": "2026-09-12T11:20:44Z"
  },
  "secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Authorization

Sent as a header on every request.

Authorizationstringrequired

A Vidrys API key, sent as Bearer vidrys_sk_…. This call changes data, so the key must be read-and-write. See Authentication.

Body

application/json

urlstringrequired

Where to POST events. HTTPS, 8–2048 characters.

eventsstring[]required

Which events to receive. At least one.

Values:run.completeddraft.ready

Response · 201

application/json

webhookobject

The new webhook.

+Show child attributes

idstring

Webhook id.

urlstring

Where events are sent.

eventsstring[]

The events it receives.

Values:run.completeddraft.ready

is_activeboolean

False once it has been switched off after 15 consecutive failed deliveries.

last_statusintegernullable

HTTP status of the latest delivery attempt.

last_delivery_atstringnullable

When the latest attempt was made (ISO 8601).

created_atstring

When it was created (ISO 8601).

secretstring

The signing secret (whsec_…). Shown once — store it now; it signs every delivery.

Errors

403 plan_feature_unavailable	The feature is on a higher plan. Bulk exports and webhooks are Custom-only.
403 write_not_allowed	The key is read-only. Writes need a read-and-write key, and read-and-write keys need Scale or Custom.
422 limit_reached	The workspace already has the maximum number of webhooks (10).
422 invalid_request	A parameter or body field is missing or has the wrong type or value. The message names the field. Also returned when a write would pass the plan's prompt limit.
401 unauthorized	No key was sent, or the key is unknown, revoked or expired, or the member who created it has left the workspace or been deactivated.
402 plan_required	The workspace's plan doesn't include API access. It's included on Grow, Scale and Custom.
403 workspace_not_approved	The workspace is still waiting for approval, or wasn't approved.
429 rate_limited	Too many requests this minute. Wait for the number of seconds in the `Retry-After` header, then retry.

Every code, and what to retry, is in Errors.