You are here:
< Back

Webhooks are “user-defined HTTP callbacks”. They are usually triggered by some event, like a comment being posted to a blog. When that event occurs, the source site makes an HTTP request to the URL configured for the webhook. Users can configure them to cause events on one site to invoke behavior on another.

When a third-party service makes a request to our webhook API, our server performs a specific action.

For example, let’s say you have a webhook set up in our system that will turn the emergency mode on on every device.
When a third-party emergency service detects a natural disaster (like earthquakes or hurricanes) in the area, it can make a request to our webhook API, and our server will react by turning the emergency mode on on all devices.

Webhooks can be used to trigger functions on devices, device groups or all devices, such as:

  • Load URL
  • Enable/Disable Emergency
  • Refresh Datasource
  • Pause Loop
  • Resume Loop
  • Send Sensor Event Data
  • Refresh Content

First, you need to create an API key.

  • You can use the eye icon to view your key.
  • You can use the pages icon to copy your key to the clipboard.
  • You can use the minus icon to delete the API key.

This key will be use to authenticate your requests.

This can be done in the settings menu under webhooks on the Webhook API keys tab.

Next, you need to create an action

When a request comes into the right endpoint and passes the authentication check the server will identify which action to trigger by the “Event ID”.

How to use the API

You can trigger webhooks in two ways by making GET or a POST HTTP request

Using method POST (recommended)

Make your request to the following URL:

{{server_root}}/public-api/integration/webhooks

  • server_root = your server (like: https://editor.wallboard.info)

You have to include the following headers:

  • Content-Type : application/json,
  • x-webhook-apikey : {{apiKey}}

You also have to pass your “event_id” in the request’s body.

{
 event_id: {{event_id}} 
} 

If you are using the send sensor event data function you need to include the ‘sensor_data’ attribute and the data in the request body.
This will only work with POST requests.

body: {
 sensor_data : "{id: '{{sensorId}}', value: '{{value}}' }",
 event_id: {{event_id}} 
}

You can also use HTTP method GET to trigger webhooks

When using the GET method you can call the webhooks by opening the URL in a browser window.

When you’re sending additional data like “sensor_data” make your request to this endpoint:

{{server_root}}/public-api/integration/webhooks?payload={payload}&apiKey={api_key}

  • server_root = your server (like: https://editor.wallboard.info)
  • api_key = the API key created in the first step
  • payload = URL and BASE64 encoded JSON object, that contains the additional data and your event_id like:

{
sensor_data : "{id: '{{sensorId}}', value: '{{value}}' }",
event_id: {{event_id}}
}

You can Base64 encode the JSON object here.

You will get something like this:

ewogc2Vuc29yX2RhdGEgOiAie2lkOiAne3tzZW5zb3JJZH19JywgdmFsdWU6ICd7e3ZhbHVlfX0nIH0iLAogZXZlbnRfaWQ6IHt7ZXZlbnRfaWR9fSAKfSA=

You can URL encode the Base 64 encoded JSON object here.

You will get a string like this:

ewogc2Vuc29yX2RhdGEgOiAie2lkOiAne3tzZW5zb3JJZH19JywgdmFsdWU6ICd7e3ZhbHVlfX0nIH0iLAogZXZlbnRfaWQ6IHt7ZXZlbnRfaWR9fSAKfSA%3D

If you don’t have additional data you need to make your request to:

{{server_root}}/public-api/integration/webhooks/triggerEvent?eventId={{yourEventId}}&apiKey={{api_key}}

  • server_root = your server (like: https://editor.wallboard.info)
  • api_key = the API key created in the first step
  • event_id = the event ID associated with your webhook action

If you are using the send sensor event data function you need to include the ‘sensor_data’ attribute and the data in the request body.
This will only work with POST requests.

body: {
 sensor_data : "{id: '{{sensorId}}', value: '{{value}}' }",
 event_id: {{event_id}} 
}

You can trigger it from a code, postman or simply opening this endpoint URL in a browser.

Here is a nodeJs sample request to trigger the webhook:

const options = {
  method: 'POST',
  url: `{{server}}/public-api/integration/webhooks`,
  headers: {
    'Content-Type': 'application/json',
    'x-webhook-apikey': {{apiKey}}
  },
  body: { event_id: {{event_id}} },
  json: true 
};
request(options, function (error, response, body) { 
  if (error) throw new Error(error);
  if (body.message === 'Error') throw new Error();
  console.log(body); //message: success
});