Skip to main content

​
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.

​
/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
Response
{"events":["creator.success", "creator.failure"]}

​
/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
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
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.
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.
Response
{"success": true}

​
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>
}
⌘I