Webhook request body

What it is

When an async task finishes, VMEG sends an HTTP POST with a JSON body to your configured webhook URL. Verify X-Timestamp and X-Signature as described in Webhook verification. The create-async HTTP response only confirms acceptance (taskId, etc.). Deliverables arrive in this webhook body, not in that response.

Common envelope

All async completion callbacks share the same top-level shape. Product-specific fields live in data:

{
  "code": 200,
  "version": "v1",
  "event": "openapi-tts",
  "pipelineKey": "a1b2c3d4e5f6789012345678901234ab",
  "message": "",
  "extraData": { "your": "memo" },
  "data": { }
}

Field	Meaning
`code`	Outcome of this delivery (`200` = task succeeded)
`version`	API version of the task (e.g. `v1`, `v2`)
`event`	Which product finished — see table below
`pipelineKey`	Stable ID for this async completion — use for receiver deduplication (see below)
`message`	Detail when `code` is not success
`extraData`	Echo of `extraData` from your async submit request (if you sent it)
`data`	Task results; schema depends on `event`

Deduplicate by `pipelineKey`

VMEG assigns one pipelineKey per accepted async run. It appears in every webhook POST for that completion.

Situation	What to do
First time you see a `pipelineKey`	Verify signature, process `data`, persist the key, return 2xx
Same `pipelineKey` again (retry)	Return 2xx quickly; do not repeat billable or irreversible work

pipelineKey is for webhook delivery deduplication. It is not the same as X-Idempotency-Key on create-async (which prevents duplicate task submission). One accepted async job has one pipelineKey; data.taskId identifies the task but retries are keyed by pipelineKey.

The `event` field

event is a string in the JSON body that tells your server which Open API product completed. Use it to route parsing logic (switch on event, then read data).

In API reference, the Callbacks block on each create-async page is named for OpenAPI tooling. The value you must implement against is the event field inside the POST JSON, not that section title.

Event values by product

Product	`event` value	Async create endpoint	What to read in `data`
Text to speech	`openapi-tts`	Create TTS (async)	Synthesis `results`, `taskId` — see Callbacks on that page
Text translation	`openapi-translate`	Create text translation (async)	`items` (translated segments), `taskId`
Voice clone	`openapi-clone-voice`	Create voice clone (async)	`voiceId` and related clone fields when successful
Media translation	`openapi-media-translation`	Create media translation (async)	`result` with CDN URLs for deliverables

Today, async task completion uses only these four event values. If we add more callback types later, they will be documented here and in the matching Callbacks schema.

Example handler routing

POST /your-webhook
  → verify signature
  → parse JSON
  → if pipelineKey already processed → return 200
  → switch (event):
       openapi-tts              → parse TTS data
       openapi-translate        → parse translation data
       openapi-clone-voice      → parse clone data
       openapi-media-translation → parse media result
  → store pipelineKey → return 200

Per-endpoint request schema

Field-level types and nested properties are defined under Callbacks on each create-async operation in API reference (linked in the table above).

Get started

Authentication

MCP

Reliable requests

Webhooks

Assets

Products

Limits

What it is

Common envelope

Deduplicate by `pipelineKey`

The `event` field

Event values by product

Example handler routing

Per-endpoint request schema

​What it is

​Common envelope

​Deduplicate by pipelineKey

​The event field

​Event values by product

​Example handler routing

​Per-endpoint request schema

What it is

Common envelope

Deduplicate by `pipelineKey`

The `event` field

Event values by product

Example handler routing

Per-endpoint request schema