⚠️ Sunset Notice: This service will be discontinued as of September 30th, 2023. Learn more »
Did you come here for Live Video Shopping?
This is documentation for Bambuser Live Streaming SDK.
If you're looking for documentation regarding Live Video Shopping (opens new window) , see these pages (opens new window)
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"
}