Webhooks

Webhooks

Download Spec

get/webhooks

List all webhooks

Retrieve a list of all webhooks configured for the current workspace.

eventsstring

The webhook event that you wish to filter on.

Example: "video.encoding.quality.completed"

currentPageint

Choose the number of search results to return per page. Minimum value: 1

Default: 1
Example: 2

pageSizeint

Results per page. Allowed values 1-100, default is 25.

Default: 25
Example: 30

Responses

Request examples

// First install the go client with "go get github.com/apivideo/api.video-go-client"
// Documentation: https://github.com/apivideo/api.video-go-client/blob/main/docs/WebhooksApi.md#list

package main

import (
    "context"
    "fmt"
    "os"
    apivideosdk "github.com/apivideo/api.video-go-client"
)

func main() {
    client := apivideosdk.ClientBuilder("YOUR_API_KEY").Build()
    // if you rather like to use the sandbox environment:
    // client := apivideosdk.SandboxClientBuilder("YOUR_SANDBOX_API_KEY").Build()
    req := apivideosdk.WebhooksApiListRequest{}
    
    req.Events("video.encoding.quality.completed") // string | The webhook event that you wish to filter on.
    req.CurrentPage(int32(2)) // int32 | Choose the number of search results to return per page. Minimum value: 1 (default to 1)
    req.PageSize(int32(30)) // int32 | Results per page. Allowed values 1-100, default is 25. (default to 25)

    res, err := client.Webhooks.List(req)
    

    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `Webhooks.List``: %v\
", err)
    }
    // response from `List`: WebhooksListResponse
    fmt.Fprintf(os.Stdout, "Response from `Webhooks.List`: %v\
", res)
}

Response examples

Success

{
  "data": [
    {
      "webhookId": "webhook_XXXXXXXXXXXXXXX",
      "createdAt": "2021-01-08T14:12:18+00:00",
      "events": [
        "video.encoding.quality.completed"
      ],
      "url": "http://clientnotificationserver.com/notif?myquery=query",
      "signatureSecret": "sig_sec_Abcd12348RLP7VPLi7nYVh"
    },
    {
      "webhookId": "webhook_XXXXXXXXXYYYYYY",
      "createdAt": "2021-01-12T12:12:12+00:00",
      "events": [
        "video.encoding.quality.completed"
      ],
      "url": "http://clientnotificationserver.com/notif?myquery=query2",
      "signatureSecret": "sig_sec_Abcd12358RLP7VPLi7nYVy"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 25,
    "pagesTotal": 1,
    "itemsTotal": 2,
    "currentPageItems": 2,
    "links": [
      {
        "rel": "self",
        "uri": "https://ws.api.video/webhooks?currentPage=1"
      },
      {
        "rel": "first",
        "uri": "https://ws.api.video/webhooks?currentPage=1"
      },
      {
        "rel": "last",
        "uri": "https://ws.api.video/webhooks?currentPage=1"
      }
    ]
  }
}

post/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.

eventsarray

required

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

Example: [ "video.encoding.quality.completed" ]

urlstring

required

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

Example: "https://example.com/webhooks"

Responses

Request examples

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

Response examples

Created

{
  "webhookId": "webhook_XXXXXXXXXXXXXXX",
  "createdAt": "2021-01-08T14:12:18+00:00",
  "events": [
    "video.encoding.quality.completed"
  ],
  "url": "http://clientnotificationserver.com/notif?myquery=query"
}

get/webhooks/{webhookId}

Retrieve Webhook details

Retrieve webhook details by id.

webhookIdstring

required

The unique webhook you wish to retreive details on.

Responses

Request examples

// First install the go client with "go get github.com/apivideo/api.video-go-client"
// Documentation: https://github.com/apivideo/api.video-go-client/blob/main/docs/WebhooksApi.md#get

package main

import (
    "context"
    "fmt"
    "os"
    apivideosdk "github.com/apivideo/api.video-go-client"
)

func main() {
    client := apivideosdk.ClientBuilder("YOUR_API_KEY").Build()
    // if you rather like to use the sandbox environment:
    // client := apivideosdk.SandboxClientBuilder("YOUR_SANDBOX_API_KEY").Build()
        
    webhookId := "webhookId_example" // string | The unique webhook you wish to retreive details on.

    
    res, err := client.Webhooks.Get(webhookId)

    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `Webhooks.Get``: %v\
", err)
    }
    // response from `Get`: Webhook
    fmt.Fprintf(os.Stdout, "Response from `Webhooks.Get`: %v\
", res)
}

Response examples

Success

{
  "webhookId": "webhook_XXXXXXXXXXXXXXX",
  "createdAt": "2021-01-08T14:12:18+00:00",
  "events": [
    "video.encoding.quality.completed"
  ],
  "url": "http://clientnotificationserver.com/notif?myquery=query"
}

delete/webhooks/{webhookId}

Delete a Webhook

This endpoint will delete the indicated webhook.

webhookIdstring

required

The webhook you wish to delete.

Responses

Request examples

// First install the go client with "go get github.com/apivideo/api.video-go-client"
// Documentation: https://github.com/apivideo/api.video-go-client/blob/main/docs/WebhooksApi.md#delete

package main

import (
    "context"
    "fmt"
    "os"
    apivideosdk "github.com/apivideo/api.video-go-client"
)

func main() {
    client := apivideosdk.ClientBuilder("YOUR_API_KEY").Build()
    // if you rather like to use the sandbox environment:
    // client := apivideosdk.SandboxClientBuilder("YOUR_SANDBOX_API_KEY").Build()
        
    webhookId := "webhookId_example" // string | The webhook you wish to delete.

    
    err := client.Webhooks.Delete(webhookId)

    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `Webhooks.Delete``: %v\
", err)
    }
}

Response examples

No Content

Empty response

webhook

Live stream started

typestring

The name of the webhook event that occurred.

Example: "live-stream.broadcast.started"

emittedAtstring

Returns the date-time when the webhook event occurred.

Format: date-time
Example: "2024-08-151T10:18:47+00:00"

liveStreamIdstring

The ID of the live stream that started broadcasting.

Example: "li400mYKSgQ6xs7taUeSaEap"

Responses

Request examples

{
  "type": "live-stream.broadcast.started",
  "emittedAt": "2024-08-151T10:18:47+00:00",
  "liveStreamId": "li400mYKSgQ6xs7taUeSaEap"
}

Response examples

Your webhook server may return this response to api.video to signal that the webhook is accepted.

Empty response

webhook

Live stream ended

typestring

The name of the webhook event that occurred.

Example: "live-stream.broadcast.ended"

emittedAtstring

Returns the date-time when the webhook event occurred.

Format: date-time
Example: "2024-08-151T10:18:47+00:00"

liveStreamIdstring

The ID of the live stream that ended broadcasting.

Example: "li400mYKSgQ6xs7taUeSaEap"

Responses

Request examples

{
  "type": "live-stream.broadcast.ended",
  "emittedAt": "2024-08-151T10:18:47+00:00",
  "liveStreamId": "li400mYKSgQ6xs7taUeSaEap"
}

Response examples

Your webhook server may return this response to api.video to signal that the webhook is accepted.

Empty response

webhook

Video source recorded

typestring

The name of the webhook event that occurred.

Example: "video.source.recorded"

emittedAtstring

Returns the date-time when the webhook event occurred.

Format: date-time
Example: "2024-08-151T10:18:47+00:00"

liveStreamIdstring

The ID of the live stream that ended broadcasting.

Example: "li400mYKSgQ6xs7taUeSaEap"

videoIdstring

The video ID of the live stream recording.

Example: "vi4blUQJFrYWbaG44NChkH11"

Responses

Request examples

{
  "type": "video.source.recorded",
  "emittedAt": "2024-08-151T10:18:47+00:00",
  "liveStreamId": "li400mYKSgQ6xs7taUeSaEap",
  "videoId": "vi4blUQJFrYWbaG44NChkH11"
}

Response examples

Your webhook server may return this response to api.video to signal that the webhook is accepted.

Empty response

webhook

Video encoding completed

typestring

The name of the webhook event that occurred.

Example: "video.encoding.quality.completed"

emittedAtstring

Returns the date-time when the webhook event occurred.

Format: date-time
Example: "2024-08-151T10:18:47+00:00"

videoIdstring

The ID of the video where a certain quality version's encoding is finished.

Example: "vi4blUQJFrYWbaG44NChkH11"

encodingstring

The type of encoding that is finished.

Enum: hls
mp4
Example: "hls"

qualitystring

The quality version of encoding that is finished.

Enum: 240p
360p
480p
720p
1080p
Example: "1080p"

Responses

Request examples

{
  "type": "video.encoding.quality.completed",
  "emittedAt": "2024-08-151T10:18:47+00:00",
  "videoId": "vi4blUQJFrYWbaG44NChkH11",
  "encoding": "hls",
  "quality": "1080p"
}

Response examples

Your webhook server may return this response to api.video to signal that the webhook is accepted.

Empty response

webhook

Video caption generated

typestring

The name of the webhook event that occurred.

Example: "video.caption.generated"

emittedAtstring

Returns the date-time when the webhook event occurred.

Format: date-time
Example: "2024-08-151T10:18:47+00:00"

videoIdstring

The ID of the video for which the caption was generated.

Example: "vi4blUQJFrYWbaG44NCh1234"

captionIdstring

The ID of the caption that was generated.

Example: "caption_1CHAfLFHT5B5EV4vzT1234"

generationModestring

Returns the method used to generate the caption. transcript means that the caption was generated based on the transcription of the video. Learn more about transcripts here.

Enum: transcript
Example: "transcript"

languagestring

Returns the language of the captions in IETF language tag format.

Enum: ar
ca
cs
da
de
el
en
es
fa
fi
fr
he
hi
hr
hu
it
ja
ko
ml
nl
nn
no
pl
pt
ru
sk
sl
te
tr
uk
ur
vi
zh
Example: "en"

Responses

Request examples

{
  "type": "video.caption.generated",
  "emittedAt": "2024-08-151T10:18:47+00:00",
  "videoId": "vi4blUQJFrYWbaG44NCh1234",
  "captionId": "caption_1CHAfLFHT5B5EV4vzT1234",
  "generationMode": "transcript",
  "language": "en"
}

Response examples

Your webhook server may return this response to api.video to signal that the webhook is accepted.

Empty response

webhook

Video summary generated

typestring

The name of the webhook event that occurred.

Example: "video.summary.generated"

emittedAtstring

Returns the date-time when the webhook event occurred.

Format: date-time
Example: "2024-08-151T10:18:47+00:00"

videoIdstring

The ID of the video for which the summary was generated.

Example: "vi4blUQJFrYWbaG44NCh1234"

summaryIdstring

The ID of the summary that was generated.

Example: "summary_1CGyYoB9XCgBk4iQna8ocT"

Responses

Request examples

{
  "type": "video.summary.generated",
  "emittedAt": "2024-08-151T10:18:47+00:00",
  "videoId": "vi4blUQJFrYWbaG44NCh1234",
  "summaryId": "summary_1CGyYoB9XCgBk4iQna8ocT"
}

Response examples

Your webhook server may return this response to api.video to signal that the webhook is accepted.

Empty response

Was this page helpful?