Sending alerts from your Bitmovin Live Encodings

Knowledge
, ,
1

Live encoding is different from vod encoding in more ways than one. One of them being that a live event is only available once - it can’t be re-done.

Running your live events via the Bitmovin Live Encoder enables a high degree of flexibility, quality, and resilience. It also provides you with options of getting alerted if different errors or encoding states should occur with your live encoding.

Alerts enable you to act only when necessary, and not needing to monitor every single live event running.

Alerts from Bitmovin Live encoder can be configured via the API - either on a per-encoding basis (e.g. when configuring the encoding) or on a global basis. Alerts are available either as e-mails (Bitmovin Docs - Encoding API Reference | Email) or as webhooks (Bitmovin Docs - Encoding API Reference | Webhooks).

For a live encoding different notification triggers are available, e.g.:

  • Encoding error - will be fired if e.g. the output storage is unavailable, or if some other error happens during the encoding)
  • Live Stream Changed notifications: these are fired when the status of the live encoding changes, eg. when transitioning from a connected ingest signal to a disconnected ingest signal, or if the ingest bitrate drops below a certain threshold.

To create a Live Stream Changed notification for a specific encoding, you would call the API with a command similar to:

curl -X 'POST' \
  'https://api.bitmovin.com/v1/notifications/webhooks/encoding/encodings/[your-live-encoding-id]/live-input-stream-changed' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: your-api-key' \
  -H 'X-Tenant-Org-Id: you-organization-id' \
  -H 'Content-Type: application/json' \
  -d '{
                    "type": "WEBHOOK",
                    "eventType": "LIVE_INPUT_STREAM_CHANGED",
                    "category": "ENCODING",
                    "muted": false,
                    "customData": "BitsReadAvg",
                    "url": "https://webhook.site/path/to/your/endpoint",
                    "method": "POST",
                    "conditions": {
                        "type": "OR",
                        "conditions": [
                            {
                                "type": "CONDITION",
                                "attribute": "bits_read_avg",
                                "operator": "<=",
                                "value": "7800000"
                            }
                        ]
                    },
                    "resolve": false,
                    "resourceType": "ENCODING"
                }'

The above webhook would fire an event to your specified endpoint if the bitrate of the ingest stream drops below 7.8 kbit/sec. “Resolve” has been set to “false”, meaning that if the ingest bitrate recovers, a “resolved” webhook notification will not be sent. Changing “resolve” to “true” would send a new webhook notification if the bitrate gets above 7.8 mbit/sec.

Using different combinations of the “resolve” tag could as an example be used to let the “fired” notification trigger an event at your backend, and if the “resolved” trigger is not received within e.g. 5 mins, trigger a pager event to the on-call technician.

The webhook notification would look something like this:

{
    "id": "79e1e4b1-3fba-4f26-a7c1-xxx",
    "eventId": "57973705-07eb-43c8-b19f-xxx",
    "createdAt": "2023-02-22T11:30:58Z",
    "modifiedAt": "2023-02-23T07:54:32Z",
    "orgId": "006d2c1d-a64b-4282-9d1a-xxx",
    "userId": "456325c4-9254-4057-8a3d-xxx",
    "notificationId": "c76b608e-9ea4-4ad5-ac78-xxx",
    "resourceId": "7bc3c154-ed19-40f4-897c-xxx",
    "resourceType": "ENCODING",
    "type": "WEBHOOK",
    "eventType": "LIVE_INPUT_STREAM_CHANGED",
    "category": "ENCODING",
    "state": "FIRED",
    "triggeredAt": "2023-02-23T08:04:00.309827742Z",
    "triggeredForResourceId": "7bc3c154-ed19-40f4-897c-xxx",
    "internal": false,
    "customData": "BitsReadAvg",
    "conditions": {
        "type": "OR",
        "conditions": [
            {
                "type": "CONDITION",
                "attribute": "bits_read_avg",
                "operator": "<=",
                "value": "7800000"
            }
        ]
    },
    "matchingConditions": {
        "type": "OR",
        "conditions": [
            {
                "type": "CONDITION",
                "attribute": "bits_read_avg",
                "operator": "<=",
                "value": "7800000"
            }
        ]
    },
    "resolve": true,
    "webhookId": "c76b608e-9ea4-4ad5-ac78-xxx"
}

Available condition attributes are:

  • connection_status
  • connection_status_just_changed
  • bits_read_avg
  • bits_read_min
  • bits_read_max
  • samples_read_avg
  • samples_read_min
  • samples_read_max
  • height
  • width
  • stream_id

We hope this can help make sure you are alerted whenever there may be a problem with your live encoding.

1 Like