VIvieneu
Public API v1

Register a webhook endpoint

Changed on

Registers an HTTPS destination that receives an event when an async job reaches a terminal state, so you can stop polling GET /v1/tts/{jobId}.

The response contains the signing secret exactly once — store it now, it cannot be retrieved again. Use it to verify the Vieneu-Signature header on every event (see the Webhooks guide).

The URL must be https and must resolve to a public address. Private, loopback, link-local, CGNAT and reserved ranges are refused here and again at the moment of each delivery, so a hostname that is re-pointed at an internal address after registration still fails.

post/api/v1/webhooks

Request

  • Base URL
    https://api.vieneu.io
  • Auth
    • API key in header X-API-Key
    • or HTTP bearer

Request body

urlstring required

HTTPS destination. Must resolve to a public address — private, loopback, link-local, CGNAT and reserved ranges are refused, both when you register the endpoint and again on every delivery attempt.

descriptionstring

Your own label. Shown back to you; never sent to the receiver.

eventsstring[]

Event types to receive. Defaults to all of them.

apiKeyIdstring

Restrict this endpoint to jobs submitted with ONE of your API keys. Omit to receive events for every key on the account. Use it to keep a test key's traffic off your production receiver.

Example request

{
  "url": "https://api.example.com/hooks/vieneu",
  "description": "Production receiver",
  "events": [
    "tts.job.completed",
    "tts.job.failed"
  ],
  "apiKeyId": "665f1a2b3c4d5e6f7a8b9c0d"
}

Response

Endpoint registered. secret is present only in this response.

idstring required
urlstring required
descriptionstring required
eventsstring[] required
status'ENABLED' | 'DISABLED' required
apiKeyIdstring nullable

Null when the endpoint receives events for every key.

secretPrefixstring required

First characters of the signing secret, so you can tell two secrets apart. The secret itself is returned ONCE, at creation and rotation.

secretRotatedAtstring date-time nullable
lastDeliveryAtstring date-time nullable
lastDeadLetterAtstring date-time nullable

When an event to this endpoint last gave up permanently.

createdAtstring date-time required
secretstring required

Signing secret. Shown ONCE — store it now, it cannot be retrieved again. Use it to verify the Vieneu-Signature header on every event.

Example response

{
  "id": "665f1a2b3c4d5e6f7a8b9c0d",
  "url": "https://api.example.com/hooks/vieneu",
  "description": "Production receiver",
  "events": [
    "tts.job.completed",
    "tts.job.failed"
  ],
  "status": "ENABLED",
  "apiKeyId": "665f1a2b3c4d5e6f7a8b9c0d",
  "secretPrefix": "whsec_a1b2c3",
  "secretRotatedAt": "2026-09-01T10:00:00Z",
  "lastDeliveryAt": "2026-09-01T10:00:00Z",
  "createdAt": "2026-09-01T10:00:00Z",
  "secret": "whsec_0000000000000000000000000000000000000000000000000000000000000000"
}

Changes

  • 98838c7c0e72Revision changes
    • info

      added the optional property to the response with the status

  • 633d63e717b8Revision changes
    • breaking

      the response property became optional for the status

    • breaking

      response property message list-of-types was widened by adding types array to media type application/json of response 400

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status