Webhooks Developer Guide

Carles Galan API, Webhooks

Overview

Webhooks allow you to collect information about events as they happen in near real-time. Provide a URL, select when and where you want that URL to receive data about events on your list, and we’ll send it to you as the events take place.

For general reading on Webhooks, read the PBWiki Webhooks page.

To test our Webhooks before setting up scripts, the RequestBin tool is an excellent utility that helps you see data come across as various events happen in our system.

Configuring Webhooks

Webhooks are configured from your webcaStudio workspace. There are two possible levels, Workspace-level webhooks and Event-level webhooks.

Creating Workspace-level Webhooks

Account-level webhooks are a collection of events triggered when certain actions happen in your workspace.

  1. Log in to your workspace console
  2. Navigate to Settings
  3. Click Workspace on left side menu
  4. Click Webhooks
  5. Click Add new webhook button

Creating Event-level Webhooks

Event-level webhooks are triggers dispatched when some actions happen in certain webcaStudio’ event.

  1. Log in to your workspace console
  2. Create a new Event or Edit an existing one
  3. Go to Webhooks tab
  4. Click Add new webhook button

Mapping

Mapping feature allows you to configure how the data will arrive to your service. It specially useful when you want to use a generic service for different purposes.

Webhooks types

Webcastudio webhooks will send an object representing the entity in webcastudio which was affected by the action triggered.

These are the possible webhook types:

Event-type

Describes the Event entity.

PropertyTypeDescription
event_idNumberEvent ID
account_idNumberWorkspace ID
event_nameStringEvent title
event_descriptionStringEvent description
event_statusStringEvent status category. Possible values: “live_pending” (green color in console), “od_pending” (blue color), “od_publisehd” (orange color).
event_start_dateStringEvent starting date
event_finish_dateStringEvent finishing date
event_languagesArray of ObjectsEvent languages
  idNumberLanguage ID
  nameStringLanguage short code (e.g. ‘en’, ‘ca’)
  labelStringLanguage description

Session-type

Describes the Session entity. A Session represent a webcast session within an Event.

PropertyTypeDescription
session_idNumberEvent session ID
event_idNumberEvent ID
account_idNumberWorkspace ID
session_nameStringSession name
session_start_datetimeStringSession starting time (including date)
session_finish_datetimeStringSession finishing time (including date)
template_idNumberPlayer template ID
app_versionStringPlayer version
session_live_statusStringSession LIVE status. Possible values:

  • off: Session is offline
  • live_publishing: Session is ready to go live but Audience is not allowed to access yet
  • live_open: Session is live and Audience may access
session_od_statusArray of ObjectsArray of languages produced OD.

NOTE: If an event’ language does not appears in array it is because this language has not been produced OD yet.

  lang_idNumberLanguage ID
  nameStringLanguage short code
  statusStringPossible values:

  • pending: Language produced but not published
  • published: Language produced and published

Supported actions

Event-type triggers

When a Event entity suffers relevant changes an action will be triggered. These are the possible actions may trigger a webhook.

ws.event.create

Dispatched when an event is created. It only affects Workspace-level webhooks.

ws.event.update

Dispatched when an event sufferers alterations in its basic properties, such as description, dates, etc.

ws.event.access_modes_update

Dispatched when an user access mode has been added or removed from an event.

Session-type triggers

Actions triggered when a Session is created or updated.

ws.session.create

Dispatched when a session has been created.

ws.session.update

Dispatched when a session has been updated. For instance, session starting date has been modified.

ws.session.status_update

Dispatched when either live or On-demand status change. For example, when a session goes live.