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 Entry/Exit 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.

An Entry 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.

An Exit 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 entry/exit notification.

Configure a Webhook

There are two ways to configure a Webhook:

• Through the Canvas UI
• Config API (Information on using the Config API for registering a Webhook can be found here.)

A new Entry/Exit webhook for an existing project can be set through the Projects section of the Dashboard.

Webhook is configured at a project level. Only one Webhook can be registered for each project. Multiple projects can be registered to post entry data to the same Webhook receiver.

To set up your Bluedot webhooks, login to Canvas and head to the Project details screen:

1. Log in to Canvas
2. Select Projects from the top right corner
3. Tap the Edit Details button
4. Tap the +Add Webhook button

Figure 1. Canvas Add webhooks button

Figure 2. Canvas webhooks section

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. Token Key: To provide additional security, we prefer to send a key-value pair as part of the request header. The Token Key is the name of the field to be sent in the POST request header. Example: “authToken” or “apiKey”
3. Token Value: The Token Value field carries the security token sent in the POST request header. Example: “f2f7a58c-f0d5-498c-9bad-acbc89923dc5” or “e4d2697bc8cc4df98ab6a88f0fd56ec3”

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 Token Key and Token Value will be sent as part of the HTTP header. The server should be able to authenticate the header of the request.

tokenKey: "tokenValue"

Example HTTP header in the request

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

Webhook response JSON structure

Fields returned in Check-in event JSON response

Entry 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"
}

Entry 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"
}

Entry 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

Exit 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"
}

Exit 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"
}

Exit 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 notification

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 notification receiver started on port 3400");