You may configure webhooks in order to be notified of events that occur throughout the Synthesia system.

When an event occurs, we send an HTTP POST request to any active webhooks that are subscribed to the applicable type of event. We expect a non-error response code (1xx, 2xx or 3xx) within six seconds in order to consider event delivery a success. In the case that event delivery fails, we will retry twice over a ten-minute window.

In order that you might verify the events you receive were sent by Synthesia, we sign each event. To learn more about verifying this signature, see this guide.

Webhook Object KeysDescription
id stringUnique identifier for the webhook.
url stringURL to which we make the HTTP POST request.
status stringThe status of the webhook, either active or deleted.
secret stringThe webhook secret which is required to verify the signature we send you.

Note that this secret is only available at time of webhook creation.
createdAt integerUNIX timestamp representing the time the webhook was created.
lastUpdatedAt integerUNIX timestamp representing the time the webhook was last updated.
{
  "id":"1234-...",
  "url":"https://webhook.site/1234-...",
  "status":"active",
  "secret":"1234-...",
  "createdAt":1623656907,
  "lastUpdatedAt":1623656907
}

Events

All events will follow the same pattern - at the top level, there will be two keys, one that describes the event that occurred and the other the event-specific payload.

Event Object KeysDescription
type stringThe event type, currently video.completed only.
dataThe event payload.

The video.completed event is sent when a video finishes processing and is as follows. Note that we do not send it when a template preview completes.

"video.completed" Object KeysDescription
id stringUnique identifier for the video.
title stringTitle of the video (used on the video's share page).
description stringDescription of the video (used on the video's share page).
visibility stringDescribes the private settings of the video.

- If public, the video's share page is active.
- If private, the video's share page is not active; visitors will receive a 404 Not Found response.
status stringDescribes the processing status of the video.

- in_progress: the video is being processed.
- complete: the video was processed successfully.
- error: an error occurred during processing.
- rejected: the video was rejected during moderation due to inappropriate content.
download stringA time-limited URL which may be used to download the video.

This field is only available if the video status is complete.
duration stringDuration of the video.

This field is only available if the video status is complete.
callbackId stringArbitrary metadata set for the video when creating the video.
createdAt integerUNIX timestamp representing the time video was created.
lastUpdatedAt integerUNIX timestamp representing the time video was last updated.
{
  "type": "video.completed",
  "data": {
    ...
  }
}
{
  "type": "video.completed",
  "data": {
    "id": "1234-...",
    "title": "Hello, World!",
    "description": "This is my first synthetic video, made with the Synthesia API!",
    "visibility": "private",
    "status": "complete",
    "download": "https://...",
    "duration": "0:00:59.000000",
    "callbackId": "[email protected]",
    "createdAt": 1602512112,
    "lastUpdatedAt": 1602512112
  }
}