Webhooks

We have recently launched a new system to configure webhooks.
If you already configured webhooks before the upgrade to 7.15, then you will be temporarily able to use both systems.
Since the old system will be dismissed in the next few months (currently there is not a deadline for this, we will publish a note into the Admin Panel), we strongly recommend you to migrate to the new system as soon as possible.

Please note that the new system will send the data in a different JSON format.

If you are looking for a guide about the old system, please check here. Below you can find more information about the new system.

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.)
  • Email verification: triggered when the user verifies his email clicking the verification link sent via email
  • Phone verification: triggered when the user verifies his phone number using one of the mechanisms provided by the platform (OTP via SMS, link via SMS)
  • Promo Page CTA: triggered when a user clicks the call to action (CTA) button in the promo page published in the Access Journey

Managing webhooks

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

The page shows a summary of the existing webhooks.

You can check if an existing webhook is enabled or not, you can check on which location it is enabled, you can edit or delete it, or make a test call to the endpoint.

 

Creating 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
  • Moment: the event that triggers the call
  • 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)
  • Headers: you can define any key-value header to include in your request
  • Body: you can choose a list of information about the event, among a given list (etc. you may want to send first name, last name, email, etc.)
  • Locations: a list of location where you want to configure the webhook

 

Webhook body


Find below the list of all the possible data returned:

  • event.type
    Possible values: dwell, leave ,login, presence, signup, space, verification.email , verification.phone
  • event.timestamp
  • event.nonce
  • event.dwellTime
  • organization.id
  • hotspot.id
  • device.deviceMac
  • device.deviceOs
  • contact.username
  • contact.id
  • contact.customFields
  • contact.extraFields
  • contact.optin
  • contact.provider
  • contact.ageVerification
  • contact.marketing
  • contact.civilStatus
  • contact.lastname
  • contact.firstname
  • contact.personalid
  • contact.email
  • contact.phone
  • contact.gender
  • contact.country
  • contact.birthday
  • contact.language
  • contact.online
  • contact.created
  • contact.metrics.visitCount
  • contact.type
  • location.tags
  • location.country
  • location.address
  • location.id
  • location.extId


Here an example how how the webhook body is formatted (this is for a sign up webhook with all attributes enabled). Note: the order may change

{
    "hotspot": {
        "id": "4fd9ca2340f699e2611d05f8b92772ff"
    },
    "contact": {
        "birthday": null,
        "country": "US",
        "firstname": "Ivan",
        "personalid": null,
        "gender": "male",
        "created": "2021-02-22T15:58:38Z",
        "customFields": [],
        "optin": [
            {
                "date": "2021-02-22T15:58:38.000Z",
                "name": "termsOfUse",
                "accepted": true,
                "id": 0,
                "type": "LEGACY",
                "version": "default"
            },
            {
                "date": "2021-02-22T15:58:38.000Z",
                "name": "privacy",
                "accepted": true,
                "id": 0,
                "type": "LEGACY",
                "version": "default"
            },
            {
                "date": "2021-02-22T15:58:38.000Z",
                "name": "mktgCommunications",
                "accepted": true,
                "id": 0,
                "type": "LEGACY",
                "version": "default"
            }
        ],
        "language": "en",
        "type": "guest",
        "civilStatus": null,
        "lastname": "Muccini",
        "marketing": true,
        "phone": "+14156234284",
        "provider": "passthrough",
        "ageVerification": null,
        "online": true,
        "id": "9c1cd25890ce9c3e439f8653ce26a1ab",
        "metrics": {
            "visitCount": 2
        },
        "email": "imuccini@cloud4wi.com",
        "extraFields": {},
        "username": "9F04472C"
    },
    "organization": {
        "id": "52f09416a85fe315019cf3d93cc90a20"
    },
    "location": {
        "country": "IT",
        "address": "Pisa",
        "extId": "4234324234",
        "id": "ff80808160b03d96016a26aaefdb74e6",
        "tags": []
    },
    "event": {
        "type": "login",
        "nonce": null,
        "timestamp": 1614009527
    }
}

How to migrate a webhook created with the old system

As already mentioned, the new system will send the data in a different JSON format.

If you want to configure a webhook sending the same information as the old version, you have to configure the headers below:


Headers

Configure the headers below:

Content-Type: application/json
Accept-Charset: UTF-8
Cf-Ipcountry: IE
Cf-Ray: 3882e1b1980f2969-DUB
Accept: application/json
Authorization: [[the value you had before for "Auth token"]]

Note: the old version had a field called "Auth token". Now you can configure the same parameters by adding a header parameter called "Authorization".

For example:
if you previously had "Auth token" = "1234567890", now you need to create a new header with key = "Authorization" and the value = "1234567890".

Body

Configure the body parameters below:

  • contact.id
  • organization.id
  • location.id
  • hotspot.id (the old system sent this info for "Sign-up" and "Login" moments only)
  • event.type
  • event.timestamp
  • contact.username
  • contact.firstname
  • contact.lastname
  • contact.gender
  • contact.phone
  • contact.email
  • contact.birthday
  • event.dwellTime (the old system sent this info for "Dwell" moments only)
  • event.nonce (the old system sent this info for "Presence", "Enter a zone", "Dwell" and "Leave" moments only)
  • contact.provider
  • contact.marketing
  • contact.type
  • contact.online (the old system sent this info for "Sign-up" and "Login" moments only)
  • contact.metrics.visitCount (the old system sent this info for "Sign-up" and "Login" moments only)
  • contact.civilStatus
  • contact.country
  • contact.optin (the old system sent this info for "Sign-up" and "Login" moments only)
  • contact.customFields (the old system sent this info for "Sign-up" and "Login" moments only)

You will no be longer able to get the following information:

  • lockedRegistration
  • deleted