Register Webhooks to receive real-time check-in/check-out notifications from your app users. This powerful feature allows you to further engage with your app users in near real time or build cool analytics.

What is a Webhook?

A WebHook is an HTTP callback: an HTTP POST that occurs when a significant event happens within Bluedot system; a simple event-notification via HTTP POST. The Check-in/Check-out Webhook lets you set up an immediate notification to your server every time someone triggers an action in your application using the Bluedot Point SDK.

A Check-In is, triggering of actions by entering a Geofence (a pre-defined geographical area), crossing a Geoline™ or coming into the configured proximity of a beacon.

A Check-out is, reporting the time spent within a Geofence (a pre-defined geographical area) or moving out of the range of a beacon.

Webhook endpoints are URLs defined by users to which Bluedot sends the check-in/check-out notification.

Configure a Webhook

There are two ways to configure a Webhook:

• Through the Bluedot Point Access UI
• Using Bluedot Public API. (Information on using the Public API for registering a Webhook can be found here.)

A new Check-in/Check-out webhook for an existing application can be set through the App & Beacon Management section of the Dashboard.

Webhook is configured at an application level. Only one Webhook can be registered for each application. Multiple applications can be registered to post check-in data to the same Webhook receiver.

Click on the Add Webhook for the application you want to register the Webhook for.

Figure 1. Point Access Add Webhook link

Webhook details to be provided

1. URL: The URL of the server where the webhooks will be received. We suggest that the service has SSL enabled.
2. Security Token Key: To provide additional security, we prefer to send a key-value pair as part of the request header. The Security Token Key is the name of the field to be sent in the POST request header. Example: “authToken” or “apiKey”
3. Security Token Value: The Security Token Value field carries the security token sent in the POST request header. Example: “f2f7a58c-f0d5-498c-9bad-acbc89923dc5” or “e4d2697bc8cc4df98ab6a88f0fd56ec3”
4. Enable Webhook: Marks the webhook as enabled. Check-ins/Check-outs will be relayed to the webhook receiver only if Enable Webhook checkbox is ticked.

Figure 2. Point Access Add Webhook Form

Receiving a Webhook notification

To receive a webhook, you would need a server that can accept and process POST requests.

Webhook response header structure

The Security Token Key and Security Token Value will be sent as part of the HTTP header. The server should be able to authenticate the header of the request.

securityTokenKey: "securityTokenValue"

Example HTTP header in the request

{
    "securitytoken": "72340732BlueDOT7297329-T0",
    "contenttype": "application/json"
}

Webhook response JSON structure

Fields returned in Check-in event JSON response

Check-in data is sent as JSON in the POST request body for the trigger of action when a device moves into a fence.

{
    "type": "checkIn",
    "checkInId":"73cbdf0c-5523-46ec-bc15-c9ad362b2a85",
    "installRef":"c92f4a32dc35282d4471b42993f809fa",
    "checkInTime": "02-09-2018 00:08:16",
    "checkInTimeISO": "2018-09-02T00:08:16.000Z",
    "longitude":144.98173087835312,
    "latitude":-37.819805462370944,
    "fenceName":"Melbourne Cricket Ground Gate 1",
    "deviceSpeed":10,
    "fenceId":"80fc36ad-ee72-4450-ad96-b3fadfc26cb4",
    "zoneName":"Melbourne Cricket Ground",
    "zoneId":"ffece0a9-fd21-4148-892e-0a61d01a6bd4",
    "deviceType":"iPhone 9,3",
    "sdkVersion": "1.13.0",
    "os": "iOS",
    "osVersion": "12.1.2",
    "appBuildVersion": "2.8.0.639",
    "receivedAt": "2018-09-02T00:22:43.816Z"
}

Check-in data is sent as JSON in the POST request body for the trigger of action when a device moves into the range of a beacon.

{
    "type": "checkIn",
    "checkInId": "61478298-25f1-49a3-91f0-2bff54c70f5e",
    "checkInTime": "02-09-2018 00:08:06",
    "checkInTimeISO": "2018-09-02T00:08:06.000Z",
    "longitude": -122.4008833,
    "latitude": 37.7917799,
    "beaconName": "Beacon at the cafe entrance",
    "beaconId": "61837732-4c30-4815-af6f-6b0f93976915",
    "deviceSpeed": 4.0,
    "installRef": "05b6f1c3-3afa-4578-bae8-59f2fbc2b5f5",
    "zoneName": "Coffee Shop",
    "zoneId": "8d615c79-c61d-4dd3-8494-75c08493d3b8",
    "deviceType": "samsung SM-G950F",
    "sdkVersion": "1.13.0",
    "appBuildVersion": "2.8.0.639",
    "os": "android",
    "osVersion": "7.0",
    "receivedAt": "2018-09-02T00:22:44.128Z"
}

Check-in data is sent as JSON in the POST request body for the trigger of action when a device moves into the range of a beacon and the custom action has custom data set in the backend and event metadata set in the SDK.

{
  "type": "checkIn",
  "checkInId":"73cbdf0c-5523-46ec-bc15-c9ad362b2a85",
  "installRef":"c92f4a32dc35282d4471b42993f809fa",
  "checkInTime": "02-09-2018 00:08:16",
  "checkInTimeISO": "2018-09-02T00:08:16.000Z",
  "longitude":144.98173087835312,
  "latitude":-37.819805462370944,
  "fenceName":"Melbourne Cricket Ground Gate 1",
  "deviceSpeed":10,
  "fenceId":"80fc36ad-ee72-4450-ad96-b3fadfc26cb4",
  "zoneName":"Melbourne Cricket Ground",
  "zoneId":"ffece0a9-fd21-4148-892e-0a61d01a6bd4",
  "deviceType":"iPhone 9,3",
  "sdkVersion": "1.13.0",
  "appBuildVersion": "2.8.0.639",
  "os": "iOS",
  "osVersion": "12.1.2",
  "receivedAt": "2018-09-02T00:22:43.816Z",
  "zoneCustomData": {
      "key1": "value1",
      "key2": "value2"
  },
  "eventMetaData": {
      "eKey1": "eValue1"
  }
}

Fields returned in Check-out event JSON response

Check-out data is sent as JSON in the POST request body for the trigger of an action when a device moves away from a fence.

{
    "type": "checkOut",
    "checkInId":"73cbdf0c-5523-46ec-bc15-c9ad362b2a85",
    "installRef":"c92f4a32dc35282d4471b42993f809fa",
    "checkInTime": "02-09-2016 00:08:16",
    "checkInTimeISO": "2016-09-02T00:08:16.000Z",
    "checkOutTime": "02-09-2016 02:25:47",
    "checkOutTimeISO": "2016-09-02T02:25:47.000Z",
    "dwellTime": 138, 
    "fenceName":"Melbourne Cricket Ground Gate 1",
    "fenceId":"80fc36ad-ee72-4450-ad96-b3fadfc26cb4",
    "zoneName":"Melbourne Cricket Ground",
    "zoneId":"ffece0a9-fd21-4148-892e-0a61d01a6bd4",
    "deviceType":"iPhone",
    "sdkVersion": "1.8.0",
    "appBuildVersion": "2.8.0.639",
    "receivedAt": "2016-09-02T02:25:47.816Z"
}

Check-out data is sent as JSON in the POST request body for the trigger of an action when a device moves out of the range of a beacon.

{
    "type": "checkOut",
    "checkInId": "61478298-25f1-49a3-91f0-2bff54c70f5e",
    "checkInTime": "02-09-2016 00:08:06",
    "checkInTimeISO": "2016-09-02T00:08:06.000Z",
    "checkOutTime": "02-09-2016 00:23:54",
    "checkOutTimeISO": "2016-09-02T00:23:54.000Z",
    "dwellTime": 16,
    "beaconName": "Beacon at the cafe entrance",
    "beaconId": "61837732-4c30-4815-af6f-6b0f93976915",
    "installRef": "05b6f1c3-3afa-4578-bae8-59f2fbc2b5f5",
    "zoneName": "Coffee Shop",
    "zoneId": "8d615c79-c61d-4dd3-8494-75c08493d3b8",
    "deviceType": "Android",
    "sdkVersion": "1.8.0",
    "appBuildVersion": "2.8.0.639",
    "receivedAt": "2016-09-02T00:23:54.128Z"
}

Check-out data is sent as JSON in the POST request body for a trigger of action when a device moves into a fence and the custom action has custom data set in the backend and event metadata set in the SDK.

{
   "type": "checkOut",
  "checkInId":"73cbdf0c-5523-46ec-bc15-c9ad362b2a85",
  "installRef":"c92f4a32dc35282d4471b42993f809fa",
  "checkInTime": "02-09-2016 00:08:16",
  "checkInTimeISO": "2016-09-02T00:08:16.000Z",
  "checkOutTime": "02-09-2016 02:25:47",
  "checkOutTimeISO": "2016-09-02T02:25:47.000Z",
  "dwellTime": 138, 
  "fenceName":"Melbourne Cricket Ground Gate 1",
  "fenceId":"80fc36ad-ee72-4450-ad96-b3fadfc26cb4",
  "zoneName":"Melbourne Cricket Ground",
  "zoneId":"ffece0a9-fd21-4148-892e-0a61d01a6bd4",
  "deviceType":"iPhone",
  "sdkVersion": "1.8.0",
  "appBuildVersion": "2.8.0.639",
  "receivedAt": "2016-09-02T02:25:47.816Z",
  "zoneCustomData": {
      "key1": "value1",
      "key2": "value2"
  },
  "eventMetaData": {
      "eKey1": "eValue1"
  }
}

Sample node.js server to receive check-ins

var express               = require('express')
var server                = express.createServer();
var expectedSecurityToken = "72340732BlueDOT7297329-T0";
 
server.post('/hooks/bluedotcheckins', function(request, response){
   var installRef     = request.body.installRef;
   var checkInId      = request.body.checkInId;
   var securityToken  = request.headers.securitytoken;
   if (securityToken == expectedSecurityToken) {
       //process the check-in/check-out notification from the Bluedot servers
       response.send(200);
   } else {
       response.send(500);
   }
});
 
server.listen(process.env.PORT || 3400);
console.log("Bluedot check-in/check-out receiver started on port 3400");

Editing an existing Webhook

Once a Webhook is created then the Add Webhook link will be changed to Edit Webhook.

Figure 3. Point Access Edit Webhook link

Click on the Edit Webbook link to access and edit the details of the registered Webhook.

Figure 4. Point Access Edit Webhook Form