Webhooks

Webhooks allow you to subscribe to a updates in the system. There is a no limit to the number of webhooks that can be added. Webhooks are useful for listening to event changes, adds, updates and deletes. It can notify when a state changes or metadata has changed. You can subscribe on a per Event basis or on a global basis.

To subscribe to changes, register your http(s) endpoints and allow them to accept POST requests.

The parameters sent by the POST request are:

    EventId: {guid} - the Id of the Event
    ReferenceId: {string} - the reference Id of the Event
    ExternalId: {string} - the external Id of the Event
    State: {EventState} - the EventState enumeration for the Event
    StateChanged: {bool} - has the state changed?
    MetadataChanged: {bool} - has the metadata changed?
    ThumbnailChanged: {bool} - has the thumbnail changed?
    IsForced: {bool} - was this a forced/manual update?
    AudioChanged: {bool} - has the audio inputs changed?
    Mp4State: {Mp4State} - the Mp4State enumeration for the Event
    Mp4StateChanged: {bool} - has the Mp4State changed?
    ChapterPointsChanged: {bool} - have the ChapterPoints changed for the Event?
    AssetsChanged: {bool} - have the associated Assets changed for the Event?
    ProvisionState: {ProvisionState} - the ProvisionState enumeration of the Event.
    ProvisionStateChanged: {bool} - has the ProvisionState changed?
    CapturingLive2VodFlagChanged: {bool} - has the `capturingLive2Vod` flag changed?
    Action: {string} - description of the action "Added", "Updated", "Deleted", or "Restored".

_Note: if opting for JSON payloads, then the above will simply be translated to a JSON body.

{
  "eventId": "2fddb651-42f7-4357-9ae4-cbc6e87a9a83",
  "referenceId": null,
  "externalId": null,
  "state": "LIVE_PUBLISHED",
  "stateChanged": true,
  "metadataChanged": false,
  "isForced": false,
  "audioChanged": false,
  "mp4StateChanged": false,
  "mp4State": "NONE",
  "chapterPointsChanged": false,
  "assetsChanged": false,
  "provisionState": null,
  "provisionStateChanged": false,
  "action": "Updated"
}

Webhook Object 

{
  "id": "a9d8e0cc-9259-453e-b34a-6fbcac2a20b9",
  "webhookUrl": "http://webhook-url-here.com",
  "useHttpBasicAuthentication": false,
  "useJsonBody": false,
  "username": "JoeBloggs",
  "password": "Password123",
  "additionalPropertiesJson": "{...}"
}

Event Specific Webhook Object 

{
  "id": "98543595-6ceb-4479-bd7e-3afe09a1b358",
  "eventId": "dc341213-2515-4ac5-988d-b35cc7dd9a86",
  "webhookUrl": "http://webhook-url-here.com",
  "useHttpBasicAuthentication": false,
  "useJsonBody": false,
  "username": "JoeBloggs",
  "password": "Password123",
  "additionalPropertiesJson": "{...}"
}

Additional Properties JSON

Example:

{
  "headers": [
    {
      "name": "x-api-version",
      "value": "2"
    }
  ]
}

Schema:

{
  "type": "object",
  "properties": {
    "headers": {
      "type": "array",
      "items": {
        "title": "header",
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1
          },
          "value": {
            "type": "string",
            "minLength": 1
          }
        },
        "required": [ "name", "value" ],
        "additionalProperties": false
      }
    }
  },
  "required": [ "headers" ],
  "additionalProperties": false
}

Example Node Application

The example Node application receives the VIS Webhook and posts the information into Slack.

https://bitbucket.org/Vuworkflow/controlhub-slack-integration-example

Supported Actions

POST /webhook/

Add or Update a system-wide Webhook.

Request Body:

{
  "id": "e6b5252c-e564-4a8f-9df0-9ef6cb15fb97",
  "webhookUrl": "http://webhook-url-here.com",
  "useHttpBasicAuthentication": false,
  "useJsonBody": false,
  "username": "JoeBloggs",
  "password": "Password123",
  "additionalPropertiesJson": "{...}"
}

If the Id is specified then it will perform an Update, else it will Add a new one.

Response: 200 OK or 400 Bad Request if the JSON is rejected.

POST /webook/event/

Add or Update an Event-specific Webhook.

Request Body:

{
  "id": "98543595-6ceb-4479-bd7e-3afe09a1b358",
  "eventId": "dc341213-2515-4ac5-988d-b35cc7dd9a86",
  "webhookUrl": "http://webhook-url-here.com",
  "useHttpBasicAuthentication": false,
  "useJsonBody": false,
  "username": "JoeBloggs",
  "password": "Password123",
  "additionalPropertiesJson": "{...}"
}

Response: 200 OK or 400 Bad Request if the JSON is rejected.

PUT /webhook/{id}

Update a system-wide Webhook by Id.

Request Body:

{
  "webhookUrl": "http://webhook-url-here.com",
  "useHttpBasicAuthentication": false,
  "useJsonBody": false,
  "username": "JoeBloggs",
  "password": "Password123",
  "additionalPropertiesJson": "{...}"
}

Response: 200 OK or 400 Bad Request if the JSON is rejected.

PUT /webhook/{id}/event/

Update an Event-specific Webhook by Id.

Request Body:

{
  "eventId": "eeae8dba-6632-4b79-b5a5-8af371316bef",
  "webhookUrl": "http://webhook-url-here.com",
  "useHttpBasicAuthentication": false,
  "useJsonBody": false,
  "username": "JoeBloggs",
  "password": "Password123",
  "additionalPropertiesJson": "{...}"
}

Response: 200 OK or 400 Bad Request if the JSON is rejected.

GET /webhook/

Get all system-wide Webhooks.

Response:

200 OK and a JSON array containing multiple Webhook objects.

or

204 No Content if no Webhooks exist.

GET /webhook/event/{eventsId}

Get all Event-specific Webhooks by Event Id.

Response:

200 OK and a JSON array containing multiple Webhook objects.

or

204 No Content if no Webhooks exist.

GET /webhook/{id}

Get a system-wide Webhook by Id.

Response:

200 OK and JSON containing a Webhook object.

or

204 No Content if no Webhook exists.

GET /webhook/{id}/event/

Get an Event-specific Webhook by Id.

Response:

200 OK and JSON containing a Webhook object.

or

204 No Content if no Webhook exists.

DEL /webhook/{id}

Delete a system-wide Webhook by Id.

Response: 200 OK

DEL /webhook/{id}/event/

Delete an Event-specific Webhook by Id.

Response: 200 OK