Webhooks

Overview

Webhooks allow you to listen to events from the Captions API once your generated videos are ready. You can specify the URL to be notified for certain events when video generation either succeeds or fails.

Webhooks are only available for customers who have signed an Enterprise contract. If you would like to use our webhook mechanism, please contact support.

Instructions

`/events`

List available webhook events to trigger notifications on the webhook URL.

Request

Request

curl -X POST https://api.captions.ai/api/webhooks/events -H "x-api-key: <api-key>"

Response Types

200 - Successful Response

`/register`

Register a webhook URL for your API account.

url - required - URL for your webhook to be notified for the provided enabledEvents.

enabledEvents - required - List of events for which your webhook should be notified.

Request

Request

curl -X POST https://api.captions.ai/api/webhooks/register -H "Content-Type: application/json" -H "x-api-key: <api-key>" -d '{"url": "https://my-business.com/my/webhook/path", "enabledEvents": ["creator.success", "creator.failure"]}'

Response Types

200 - Successful Response

A successful response contains a secret and a unique ID, both of which you should store. We will use this secret as an Authorization Bearer token so that you can confirm our API as the caller.

Response

{"id": "<unique-webhook-id>", "secret":"<secret-you-should-store>", "url": "https://my-business.com/my/webhook/path", "enabledEvents": ["creator.success", "creator.failure"]}

`/list`

List registered webhooks for your API account.

Request

Request

curl -X POST https://api.captions.ai/api/webhooks/list -H "x-api-key: <api-key>"

Response Types

200 - Successful Response

A successful response contains a list of webhook objects, each with their own unique ID, the webhook URL, a unique secret, and a list of enabled events for that webhook.

Response

{"registeredWebhooks":[{"id":"<unique-webhook-id1>","url":"https://my-business.com/my/webhook/path1","secret":"<secret-you-should-store1>","enabledEvents":["<event1>"]},{"id":"<unique-webhook-id2>","url":"https://my-business.com/my/webhook/path2","secret":"<secret-you-should-store2>","enabledEvents":["<event1>", "<event2>"]}]}

`/update`

Update a registered webhook’s URL and/or enabled events.

id - required - ID for the webhook to be updated.

url - optional - New URL for your webhook to be notified for the provided or existing enabledEvents.

enabledEvents - optional - Updated list of events for which your webhook should be notified.

200 - Successful Response

A successful response contains a new secret and a the existing ID as well as the updated URL and enabled events. We will use the new secret as an Authorization Bearer token so that you can confirm our API as the caller.

Response

{"id": "<unique-webhook-id>", "secret":"<secret-you-should-store>", "url": "https://my-business.com/my/webhook/path", "enabledEvents": ["creator.success", "creator.failure"]}

`/delete`

Delete a registered webhook.

id - required - ID for the webhook to be deleted.

200 - Successful Response

Usage

Once your webhook is registered, you can call the AI Creator API with a /submit request without having to poll. Our API will post a request to your registered webhook URL with the following signature once your video generation is ready:

Request

Headers:
Content-Type: application/json
Authorization: Bearer <secret-you-should-store>

{
    "url": "<signed-video-url>",
    "event": "creator.success",
    "operationId": "<operation-id>",
    "creditsSpent": <number-of-credits-spent>
}

GET STARTED

GENERATE VIDEO

EDIT VIDEO

LINK TO VIDEO

RECORD VIDEO

AI FEATURES

TIMELINE EDITING

WORKFLOWS

SETTINGS & ACCOUNT

APIs & Integrations

Overview

`/events`

`/register`

`/list`

`/update`

`/delete`

Usage

GET STARTED

GENERATE VIDEO

EDIT VIDEO

LINK TO VIDEO

RECORD VIDEO

AI FEATURES

TIMELINE EDITING

WORKFLOWS

SETTINGS & ACCOUNT

APIs & Integrations

​Overview

Overview