Webhooks

Create Webhook

Webhooks can push notifications to your server, rather than polling api.video for changes. We currently offer four events:

video.encoding.quality.completed Occurs when a new video is uploaded into your account, it will be encoded into several different HLS and mp4 qualities. When each version is encoded, your webhook will get a notification. It will look like { "type": "video.encoding.quality.completed", "emittedAt": "2021-01-29T16:46:25.217+01:00", "videoId": "viXXXXXXXX", "encoding": "hls", "quality": "720p"} . This request says that the 720p HLS encoding was completed.
live-stream.broadcast.started When a live stream begins broadcasting, the broadcasting parameter changes from false to true, and this webhook fires.
live-stream.broadcast.ended This event fires when a live stream has finished broadcasting.
video.source.recorded This event occurs when a live stream is recorded and submitted for encoding.
video.caption.generated This event occurs when an automatic caption has been generated.
video.summary.generated This event occurs when an automatic summary has been generated.

post/webhooks

Request body

eventsstring[] required

An array of webhook events that you want to subscribe to.

urlstring required

The the url to which HTTP notifications are sent. It could be any http or https URL.

Example request

{
  "events": [
    "video.encoding.quality.completed"
  ],
  "url": "http://clientnotificationserver.com/notif?myquery=query"
}

Response

Created

webhookIdstring

A unique identifier of the webhook you subscribed to.

createdAtstring date-time

The time and date when you created this webhook subscription, in ATOM UTC format.

eventsstring[]

A list of events that you subscribed to. When these events occur, the API triggers a webhook call to the URL you provided.

urlstring

The URL where the API sends the webhook.

signatureSecretstring

A secret key for the webhook you subscribed to. You can use it to verify the origin of the webhook call that you receive.

Example response

{
  "createdAt": "2019-06-24T11:45:01Z",
  "webhookId": "webhook_XXXXXXXXXXXXXXX",
  "events": "[\"video.encoding.quality.completed\"]",
  "url": "http://clientnotificationserver.com/notif?myquery=query",
  "signatureSecret": "signatureSecret"
}

Changes

Changed in 4 of the 50 revisions of this API.6713

Oct 2, 2024ebf0925369031See the full diff
- ○
  added the optional property to the response with the status
  response-optional-property-added
Apr 16, 2024ec2b79bfdc8d1See the full diff
- ○
  added the non-success response with the status
  response-non-success-status-added
Apr 28, 2022f9532dd3578c2See the full diff
- ○
  the endpoint scheme security apiKey was added to the API
  api-security-added
- ○
  the endpoint scheme security bearerAuth was removed from the API
  api-security-removed
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Feb 7, 20222a4d90a64f88679See the full diff
- ▲
  removed the enum value live-stream.broadcast.ended of the request property /
  request-property-enum-value-removed
- ▲
  removed the enum value live-stream.broadcast.started of the request property /
  request-property-enum-value-removed
- ▲
  removed the enum value video.caption.generated of the request property /
  request-property-enum-value-removed
- ▲
  removed the enum value video.encoding.quality.completed of the request property /
  request-property-enum-value-removed
- ▲
  removed the enum value video.source.recorded of the request property /
  request-property-enum-value-removed
- ▲
  removed the enum value video.summary.generated of the request property /
  request-property-enum-value-removed
- ●
  the optional response header X-RateLimit-Limit removed for the status 201
  optional-response-header-removed
- ●
  the optional response header X-RateLimit-Limit removed for the status 400
  optional-response-header-removed
- ●
  the optional response header X-RateLimit-Remaining removed for the status 201
  optional-response-header-removed
- ●
  the optional response header X-RateLimit-Remaining removed for the status 400
  optional-response-header-removed
- ●
  the optional response header X-RateLimit-Retry-After removed for the status 201
  optional-response-header-removed
- ●
  the optional response header X-RateLimit-Retry-After removed for the status 400
  optional-response-header-removed
- ●
  removed the optional property from the response with the status
  response-optional-property-removed
- ○
  the endpoint scheme security bearerAuth was added to the API
  api-security-added
- ○
  the endpoint scheme security apiKey was removed from the API
  api-security-removed
- ○
  removed the non-success response with the status
  response-non-success-status-removed
- ○
  removed the live-stream.broadcast.ended enum value from the / response property for the response status
  response-property-enum-value-removed
- ○
  removed the live-stream.broadcast.started enum value from the / response property for the response status
  response-property-enum-value-removed
- ○
  removed the video.caption.generated enum value from the / response property for the response status
  response-property-enum-value-removed
- ○
  removed the video.encoding.quality.completed enum value from the / response property for the response status
  response-property-enum-value-removed
- ○
  removed the video.source.recorded enum value from the / response property for the response status
  response-property-enum-value-removed
- ○
  removed the video.summary.generated enum value from the / response property for the response status
  response-property-enum-value-removed
This revision also has 32 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Of the 50 revisions, 1 has no diff computed.

Full history