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.
/events
List available webhook events to trigger notifications on the webhook URL.
Request
curl -X POST https://api.captions.ai/api/webhooks/events -H "x-api-key: <api-key>"
Response Types
{"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
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.
{"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
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.
{"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.
{"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.
{"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:
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>
}
Was this page helpful?