Webhooks Menu

Webhooks

Webhooks are “user-defined HTTP callbacks”. They are usually triggered by an 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 behaviour 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 for 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 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
• Restart device

First, you need to create an API key.

You can use this button to view your key.

You can use this button to copy your key to the clipboard.

You can use this button to delete the API key.

‍This key will be used 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”.

With this button, you can generate a URL which can trigger the webhook and you do not need to create the whole request to access the API. 

How to use the API

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

Using method POST

Make your request to the following URL:

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

• server_root = your server (like: https://app.peaksignage.com)

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’s body.

{ “sensor_data” : {“id”: “{{sensorId}}”, “event”: “{{sensorEvent}}”, “value”:”eventValue”},

“event_id”: “{{event_id}}” }

Using method GET

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

Example URL of the Webhook call:

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

• server_root = your server (like: https://app.peaksignage.com)
• 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.

Payload

{“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 payload.

{ “sensor_data” : {“id”: “{{sensorId}}”, “event”: “{{event}}”, “value”:”eventValue”},

“event_id”: “{{event_id}}” }

Fill the payload with the correct data and Base64 and URL encode it. 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

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

});