Webhooks

Webhook is a technical name to indicate a web-based notification that sends a message to an URL when certain actions happen.

Cloud4Wi allows you to setup a webhook the following types of event:

  • Sign-up: the event is triggered after a user is registered to the database (either registration from the Splash Page, Cloud4Wi Dashboard or Kiosk)
  • Login: the event is triggered after a guest user signs-in on the guest Wi-Fi
  • Presence: the event is triggered after a user's device is detected by the access point
  • Enter a Zone: this even is triggered when the customer enters in one of the zones (Virtual or Polygons) configured in the webhook options
  • Dwell: this even is triggered when the customer dwell a specific amount of time (configurable in the options) in a location
  • Leave: this event is triggered when the customer leave a location. The event is triggered only when the system doesn't receive any signal form the customer for more than a specific period (configurable in the settings of your Cloud4Wi Org.)

mceclip0.png

Webhooks can be created in the Cloud4Wi Dashboard of your Cloud4Wi Company Account, from Manage > Notifications.

The page shows a summary of the existing webhooks.

webhooks_list.png

  • For each webhook, you can check the percentage of notifications that have been delivered successfully and those which originated an error.
  • You can specify a list of venues where the webhook is enabled
  • You can enable or disable the webhook
  • You can test the webhook by clicking on the test icon

Note: at the moment you can not edit an existing webhook. You can delete and then re-create it with different settings.

Create a webhook

To create a webhook you have to click on the Add button on the top of the page.

On the next page, you can set the following data:

  • Name: name of your webhook, for inventory purposes
  • Type: type of event, either login or sign-up
  • URL: end-point of the HTTP POST request (for example https://yourdomain.com/myapps/webhook.com), The end-point of the HTTP POST request of the webhook can be http and https; if https the server must be correctly configured in order to support the Server Name Indication (SNI) (https://en.wikipedia.org/wiki/Server_Name_Indication).
  • Auth Token: validation code that will be included in the header of each HTTP POST request so that the receiver can validate the source of the POST
  • Venues: the venues where the webhook can be triggered

webhooks_add.png

Limitations:

At the moment you can not edit existing a webhook. But you can delete and then re-create it.

Technical details:

The Auth Token is included in the HTTP header of the POST request with the name "Authorization".

 

HEADERS

Content-Type: application/json
Accept-Charset: UTF-8
Cf-Ipcountry: IE
Cf-Ray: 3882e1b1980f2969-DUB
Accept: application/json
Authorization: 1234567890

The HTTPS POST data is a JSON file containing the following dataset:

{
 "userId":"0ef3d69c170266937600e16b7189c037",
 "tenantId":"617d17a5639aea2f7728f48d251b9def",
 "venueId":"2c9f929f59b1881b015a3726ab880b8d",
 "hotspotId":"344759de5464435d80cf0e2780247975",
 "event":"login",
 "timestamp":1562753268,
 "username":"BDF017C0",
 "firstName":"Ivan",
 "lastName":"Muccini",
 "gender":"",
 "phone":"+14151234567",
 "email":"imuccini@cloud4wi.com",
 "birthDate":"",
 "provider":"cloud4wi",
 "marketing":false,
 "type":"guest",
 "online":true,
 "visitCount":"1",
 "lockedRegistration":false,
 "deleted":false,
 "civilStatus":"Mr",
 "country":"IT",
 "customOptin":{
  "myCustomOptInClause_1":false
  "myCustomOptInClause_2":true
 }
}

Notes:

  • The hotspotId parameter is not available on the Sign-Up webhook when users register from a Kiosk or they are manually created from the Cloud4Wi Dashboard.
  • The customOptin key contains all the defined custom opt-in clauses. In case no clause is defined on the organization, then the key will not appear.

Listener example in PHP

Here a simple example to catch the webhook message and parse the data:

< ? php

$headers = getallheaders(); //get headers
$jsonPayload = file_get_contents('php://input'); //get the json body
$aPayload = json_decode($jsonPayload, true);  //headers
$auth = $headers['Authorization'];  //payload
$event = $aPayload['event'];
$userId = $aPayload['userId'];
$tenantId = $aPayload['tenantId'];  echo $auth;
echo $event;
echo $userId;
echo $tenantId;   
?>