Web Hooks

Dolby.io Real-time Streaming uses webhooks to notify your application when an event happens in your account. A webhook enables Dolby.io Real-time Streaming to push real-time notifications to your app.

There are three types of hooks available, feeds hooks, which allow you to receive events when a stream has been published or stopped publishing, and recording hooks, which allow you to receive notifications about the life cycle of a stream recording, and thumbnail hooks, which allow you to preview a thumbnail image of your video stream. The Webhooks REST APIs allow you to add, configure, remove, and get information about webhooks on your account.

Dolby.io Real-time Streaming uses HTTPS POST request to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your backend systems.

All the Dolby.io Real-time Streaming webhooks share the same JSON structure:

{ 
  "type": "webookType", // Webhook type: "feeds", "recording", or "thumbnail"
  "event": "eventName", // Event name, for example "started" or "ended" for "feeds" webhooks 
  "timestamp": 1638463486489,        // Timestamp when the webhook request was sent
  "data": {
    // Event payload
  }
}

Where:

• type is the webhook type. Currently there are three types of hooks: "feeds", "recording", and "thumbnail".
• events is the actual event type, the available value depends on the type of the webhook.
• timestamp the epoc timestamp in seconds when the POST request was sent by Dolby.io Real-time Streaming.
• data the event payload.

The webhooks HTTP POST request body will be protected using a signature with the format "sha1="+hmac(body,secret) which be sent in a X-Millicast-Signature HTTP header of the POST.

const webhookSecretBuffer = Buffer.from(webhookSecret, 'base64');
    const calculatedSignature = 'sha1=' + Crypto.createHmac('sha1', webhookSecretBuffer)
        .update(body)
        .digest('hex');
    const headerSignature = request.get('X-Millicast-Signature');

    if (calculatedSignature !== headerSignature) {
      console.warn('Invalid signature sent to us, unsafe data');
      res.status(400).send('BAD SIGNATURE');
      return;
    }

Dolby.io Real-time Streaming will not retry the webhooks in case of failure and processes them asynchronously, so it is very unlikely, but if you start publishing and then immediately stop it, it may happen that you receive the stop event before the started one, so you should be ready for this contingency.