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 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 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.

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"
}