How to use webhooks to sync broadcasts to your backend

In most Bambuser customer implementations, having all broadcasts and uploaded images represented in a local database is convenient, perhaps even a requirement. Webhooks provides an efficient way to automatically receive information about the material your clients produce to your backend.

Configuring webhooks

Go to the Developer (opens new window) page on the Bambuser site to add webhooks for your Sandbox or Production environment.

Receiving and responding to webhook notifications

Create an endpoint which accepts POST requests on your server. Webhook data is sent as JSON in the POST request body.

Your server should respond with a 200 OK HTTP response status code. Should your server respond with any other status code or be unreachable: see Retries. On the Developer (opens new window) page you may verify the response status code by clicking the Test button. 200 OK results in a successful test, any other response code will result in a failure.

Webhook notifications

Webhook notifications are categorized by collection and action properties and contain a payload with additional properties where applicable.

collection	action	payload	description
broadcast	add	id and various properties.	Sent for new broadcasts.
broadcast	update	id and various properties.	Sent when broadcast metadata is updated.
broadcast	remove	id.	Sent when a broadcast is removed.
broadcast	extract	id and status.	Sent when broadcast clip extraction status changes. Status error indicates that the extract-operation could not produce a broadcast. Status may be expanded in the future.
image	add	id and various properties.	Sent for new images.
image	update	id and various properties.	Sent when image derivatives are generated.
image	remove	id.	Sent when an image is removed.

Webhooks may be expanded with new collections, actions and payload properties. Your server should act on specific collections and actions you recognize. Your server should respond with 200 OK even for a notification you don't recognize, or it will be retried, see Retries.

Example webhook notification

Below is an example of what a webhook notification may look like. Take special note of the type field. When a live broadcast ends, the value in the type field will change to archived.

{
  "action": "add",
  "collection": "broadcast",
  "payload": {
    "author": "Sveninge Bambuser",
    "created": 1474033783,
    "customData": "",
    "height": 540,
    "id": "9353eaec-794f-11e6-97c0-f19001529702",
    "ingestChannel": "cfc8626c-9a0e-ab78-6424-3eb0978d8e45",
    "lat": 63.205312,
    "length": 0,
    "lon": 17.13011,
    "positionAccuracy": 25,
    "positionType": "GPS",
    "preview": "https://archive.bambuser.com/9353eaec-794f-11e6-97c0-f19001529702.jpg",
    "resourceUri": "https://cdn.bambuser.net/broadcasts/9353eaec-794f-11e6-97c0-f19001529702?da_signature_method=HMAC-SHA256&da_id=9353eaec-794f-11e6-97c0-f19001529702&da_timestamp=1474033783&da_static=1&da_ttl=0&da_signature=eaf4c9cb29c58b910dcbad17cf7d8a3afa4e6a963624ba4c4fd0bb5bade1cdd6",
    "tags": [
      {
        "text": "whoa"
      }
    ],
    "title": "Amazing!",
    "type": "live",
    "width": 960
  },
  "eventId": "93df93061a891c23"
}

Below is an example of what a webhook notification for an uploaded image may look like.

{
  "action": "add",
  "collection": "image",
  "payload": {
    "added": 1476177324,
    "author": "Sveninge",
    "created": 1447247377,
    "customData": "",
    "derivatives": [
      {
        "title": "small",
        "url": "https://archive.bambuser.com/4ee15d99-826f-11e6-b000-0811968eca44-1.jpg",
        "width": 250,
        "height": 187
      },
      {
        "title": "medium",
        "url": "https://archive.bambuser.com/4ee15d99-826f-11e6-b000-0811968eca44-2.jpg",
        "width": 750,
        "height": 562
      },
      {
        "title": "large",
        "url": "https://archive.bambuser.com/4ee15d99-826f-11e6-b000-0811968eca44-3.jpg",
        "width": 1000,
        "height": 750
      }
    ],
    "height": 3264,
    "id": "e3ed1592-8fb1-11e6-9a9c-f9b49ceed562",
    "ingestChannel": "cfc8626c-9a0e-ab78-6424-3eb0978d8e45",
    "lat": 0,
    "lon": 0,
    "originalFilename": "IMG-0002.jpg",
    "title": "Test broadcast",
    "url": "https://archive.bambuser.com/e3ed1592-8fb1-11e6-9a9c-f9b49ceed562.jpg",
    "width": 2448
  },
  "eventId": "93df93061a891c23"
}

Note

Smaller versions of uploaded images (found in the derivatives list) are created asynchronously. This means the first notification for an image may lack derivatives, but they will come in a second webhook notification (with action=update) sent a short while later.

Warning

In very rare cases, the same webhook notification may be sent multiple times. Please ensure that your server can handle this accordingly.

Retries

If an endpoint is unreachable or your server does not respond with a 200 OK HTTP response status, the webhook notification will be placed on hold and an attempt to resend the notification will take place after a little while.

Webhook verification

GET /events/:eventId

By requesting a previously sent webhook directly from the source using the eventId property, the contents and origin of the webhook can be verified. Below is an example of such a request.

Example request

curl -XGET "https://webhook.bambuser.io/events/93df93061a891c23"

Example response

{
    "action": "add",
    "collection": "broadcast",
    "payload": {
        "author": "Sveninge Bambuser",
        "created": 1474033783,
        "customData": "",
        "height": 540,
        "id": "9353eaec-794f-11e6-97c0-f19001529702",
        "ingestChannel": "cfc8626c-9a0e-ab78-6424-3eb0978d8e45",
        "lat": 63.205312,
        "length": 0,
        "lon": 17.13011,
        "positionAccuracy": 25,
        "positionType": "GPS",
        "preview": "https://archive.bambuser.com/9353eaec-794f-11e6-97c0-f19001529702.jpg",
        "resourceUri": "https://cdn.bambuser.net/broadcasts/9353eaec-794f-11e6-97c0-f19001529702?da_signature_method=HMAC-SHA256&da_id=9353eaec-794f-11e6-97c0-f19001529702&da_timestamp=1474033783&da_static=1&da_ttl=0&da_signature=eaf4c9cb29c58b910dcbad17cf7d8a3afa4e6a963624ba4c4fd0bb5bade1cdd6",
        "tags": [
        {
            "text": "whoa"
        }
        ],
        "title": "Amazing!",
        "type": "live",
        "width": 960
    },
    "eventId": "93df93061a891c23"
}