Custom API Calls (Webhooks)

This section will be added to all push destination articles.

---

Configure Custom API Calls (Webhooks)

With the Custom API configuration events (Webhooks), you can start/stop external services, transmit the playing element metadata such as title and description, and transmit ad-trigger information to external APIs. (Available since version 9.5)

These API webhooks can be configured and activated by switching on the five API configuration event areas for each output push destination (RTMP, HLS, SRT, TCP, and UDP) as needed.

Beside the push destinations, webhooks are also available for events (ad-break) configurations:

For events you are able to to configure one webhook per event. For output target destinations you can configure different webhooks for Publish Start, Publish Stop, Ad Start, Ad End and Element Switch. You can find detailed descriptions below how the configuration should be done.

Within the webhook triggers you can also use some variables, you can hand over within the webhook string inside of curly brackets {}. The available variables are:

{AD_DURATION}
{PREROLL}
{TITLE}
{DESCRIPTION} 

• {AD_DURATION} --> this inserts the ad-duration in seconds.
• {PREROLL} --> this inserts the configured preroll duration in seconds.
• {TITLE} --> this inserts the title of the current playing element. 
• {DESCRIPTION} --> this inserts the description of the current playing element. 

How to configure a webhook api call

• Publish Start: This webhook is called when Schedule starts pushing to this target.
• Publish Stop: This webhook is called when Schedule stops pushing to this target, such as when it's disabled or playback is stopping.
• Ad Start: This webhook is called when an advertisement call is starting. This could be triggered by a received SCTE, manual ad break, VOD ad break, or any other relevant event. You can also add AD_DURATION and PREROLL (seconds) values, configured for assets of your playlist, within the API string with {} like this {AD_DURATION} to hand over those values to the external API. 
  • Example:

  • "method": "POST"
    "requestUrl": "http://localhost:59191/ad/{AD_DURATION}/{PREROLL}"
    

• Ad End: This webhook is called when the started advertisement call has been cancelled. This could be triggered by a received SCTE for cancelling or manual cancellation.
  • Example:

  • "method": "GET"
    "requestUrl": "http://localhost:59191/adcancel"
    

• Element Switch: This feature is called when the playlist switches to the next element.
  • Example:

  • "method": "GET"
    "requestUrl": "http://localhost:59191/switch/{TITLE}/{DESCRIPTION}/{PREROLL}"
    

To use a custom API Call:

1. Switch on one or multiple webhooks you want to use
2. Enter the API URL
3. Select one of the Methods GET, PUT, PATCH or POST
4. Optional: If you want to use a request header, enter the header name
5. and the header value
6. Optional: If you want to use multiple request headers, click the plus button to get more inputs
7. Optional: If you want to use a request body, enter the body value. (only for PUT, PATCH, POST method)