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 Keys

Description

id string

Unique identifier for the webhook.

url string

URL to which we make the HTTP POST request.

status string

The status of the webhook, either active or deleted.

secret string

The 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 integer

UNIX timestamp representing the time the webhook was created.

lastUpdatedAt integer

UNIX 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 Keys

Description

type string

The event type, currently video.completed only.

data

The 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 Keys

Description

id string

Unique identifier for the video.

title string

Title of the video (used on the video's share page).

description string

Description of the video (used on the video's share page).

visibility string

Describes 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 string

Describes 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 string

A time-limited URL which may be used to download the video.

This field is only available if the video status is complete.

duration string

Duration of the video.

This field is only available if the video status is complete.

callbackId string

Arbitrary metadata set for the video when creating the video.

createdAt integer

UNIX timestamp representing the time video was created.

lastUpdatedAt integer

UNIX 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
  }
}