Webhooks

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.

image

As of v1.9.1 a webhook notification will be sent for check-in and check-out events.

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

Field Description
appBuildVersion The app build version of the application using the Point SDK which triggered the check-in. (Available only for check-ins of SDK version 1.8 and above.)
beaconId The unique identifier of the beacon that triggered the Check-in. Not returned for geo-fence Check-ins.
beaconName The name of the beacon that triggered the Check-in event. Not returned for geo-fence Check-ins.
checkInId The unique identifier of the Check-in record.
checkInTime UTC date and time of the Check-in in DD-MM-YYYY hh:mm:ss format.
checkInTimeISO UTC date and time of the Check-in in ISO format.
deviceSpeed The travel speed of the device at the time of Check-in, reported as meters per second.
deviceType The type of device that triggered the Check-in event. Reported as either Android or iOS.
eventMetaData Key/Value pairs passed from the application to Bluedot Point SDK.
fenceId The unique identifier of the fence that triggered the Check-in.
fenceName The name of the geofence that triggered the Check-in.
installRef The unique app install reference on the device.
latitude Latitude component of the coordinate at which the Check-in occurred.
longitude Longitude component of the coordinate at which the Check-in occurred.
receivedAt UTC date and time of the Check-in was received in our database in ISO format.
sdkVersion The Point SDK version number being used in the application which has triggered the check-in. (Available only for check-ins of SDK version 1.6 and above.)
type This field denotes the type of event being relayed from our servers to yours. For check-ins the type will be “checkIn”.
zoneCustomData Key/Value pair of Location specific data added to the custom action of the Zone.
zoneId The unique identifier of the zone that triggered the Check-in.
zoneName The name of the zone that triggered the Check-in.

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

{
    "type": "checkIn",
    "checkInId":"73cbdf0c-5523-46ec-bc15-c9ad362b2a85",
    "installRef":"c92f4a32dc35282d4471b42993f809fa",
    "checkInTime": "02-09-2016 00:08:16",
    "checkInTimeISO": "2016-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",
    "sdkVersion": "1.8.0",
    "appBuildVersion": "2.8.0.639",
    "receivedAt": "2016-09-02T00:22:43.816Z"
}

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

{
    "type": "checkIn",
    "checkInId": "61478298-25f1-49a3-91f0-2bff54c70f5e",
    "checkInTime": "02-09-2016 00:08:06",
    "checkInTimeISO": "2016-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": "Android",
    "sdkVersion": "1.8.0",
    "appBuildVersion": "2.8.0.639",
    "receivedAt": "2016-09-02T00:22:44.128Z"
}

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

{
  "type": "checkIn",
  "checkInId":"73cbdf0c-5523-46ec-bc15-c9ad362b2a85",
  "installRef":"c92f4a32dc35282d4471b42993f809fa",
  "checkInTime": "02-09-2016 00:08:16",
  "checkInTimeISO": "2016-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",
  "sdkVersion": "1.8.0",
  "appBuildVersion": "2.8.0.639",
  "receivedAt": "2016-09-02T00:22:43.816Z",
  "zoneCustomData": {
      "key1": "value1",
      "key2": "value2"
  },
  "eventMetaData": {
      "eKey1": "eValue1"
  }
}

Fields returned in Check-out event JSON response

Fields Description
checkOutTime UTC date and time of the Check-out in DD-MM-YYYY hh:mm:ss format.
checkOutTimeISO UTC date and time of the Check-out in ISO format.
dwellTime The dwell time is the number of minutes a device was within a fence or within the range of a beacon.
type This field denotes the type of event being relayed from our servers to yours. For check-outs the type will be “checkOut”.

Check-out data is sent as JSON in the POST request body for 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 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 an action when a device moves into a fence and the custom action of the Zone has custom data and event metadata is 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

Created by Bluedot DevOps on January 11, 2018

Start the discussion

    2 Comments

  1. Praveen

    hi, we are using bluedot in our application. we are successfully able to create application with webhook and zones etc. but we are not able to understand how to create webhook callback url. so could you please give us brief about the webhook callback url.
    Thanks in adbance.

    • Ram Akunuru

      Hi Praveen,

      Thanks for reaching out to us. Webhook callback URL should be the URL of the server where the check-ins/check-outs are to be received and processed on your system.