Webhooks

You can use webhooks to send Moments from Cloud4Wi to your server, a Google or Firebase Cloud Function, an AWS Lambda Function, or any HTTP endpoint. From there, you can store events in a database, send them to a marketing automation or analytics platform, and more.

You can also directly integrate Moments with your enterprise CDPs or Marketing Automation platforms such as Salesforce Marketing Cloud. Before getting started with webhook, check our Connectors to see if there is already a plug and play integration you can use, or contact our team to request a custom integration.

Cloud4Wi webhooks also allow you to sync in real-time Contacts with your CRM, and push all application events generated by Cloud4Wi marketing tools (such as messages, surveys, offers) to external datasets.

Event types

• Sign-up: the event is triggered after a user sign up from any of the CLoud4Wi acquisition experiences (either registration from the Splash Page, Cloud4Wi Dashboard or Kiosk) Event > type attribute signup

• Login: the event is triggered after a guest user signs in on a guest Wi-Fi network, both via captive portal, WPA2 Enterprise or Passpoint. Event > type attribute login

• Presence: the event is triggered after a user's device is detected for the first time in a Location. Event > type attribute presence

• Enter a Zone: this event is triggered when the user enters one of the Location zones (Virtual or Polygons) configured in the webhook options Event > type attribute space

• Dwell: this event is triggered when the user dwell a specific amount of time (configurable in the options) in a Location Event > type attribute dwell

• Leave: this event is triggered when the customer leaves a Location. The event is triggered only when the system doesn't receive any signal from the customer for more than a specific period (configurable in the settings of your Cloud4Wi account.) Event > type attribute leave

• Geo Events: this webhook is triggered whenever a mobile user enters or exist from a geofence. If you configured the geofence with a minimum dwell time, the entry event will trigger only if the user is detected with enough confidence in the geofence for the minimum amount of time configured. The possible values for the event > type attributes are:

  • geo-arriving

  • geo-dwell

  • geo-leave

• Email verification: triggered when the user verifies his email by clicking the verification link sent via email Event > type attribute verification.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) Event > type attribute verification.phone

• Promo Page CTA: triggered when a user clicks the call to action (CTA) button in the promo page published in the Access Journey Event > type attribute promopageaction

• Marketing Events: this webhook is triggered when a marketing-related evnet happens. For example when the user responds to a survey published in the Access Journey, or the user receives messages, open them or clicks links on them ( messages configured by the Campaign tool), or when user clicks the call to action (CTA) button in the promo page published in the Access Journey. The possible values for the event > type attributes are:

  • answer_survey

  • prx_send_email,prx_send_sms

  • prx_open_email

  • prx_click_email,prx_click_sms

  • promo_cta

Configuration

You can manage webhooks on the Cloud4Wi dashboard Developers page under Webhooks. To create a webhook you have to click on the Add button at the top of the page, then enter the required 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 attributes to send about the event, among a given list (etc. you may want to send first name, last name, email, etc.)

• Locations: optional, for on-site event you can filter the webhooks that occur only in a specific list of locations

Whenever events are generated, Cloud4Wi will send a POST request containing the configured body to the specified URL. You can also click the Test (magic ward) icon to send test event. To acknowledge receipt of the request, your webhook should return a 2xx status code (e.g., 200 OK, 201 Created, or 202 Accepted).

Sample request

{
	"hotspot": {
		"id": "4fd9ca2340f699e2611d05f8b92772ff"
	},
	"contact": {
		"birthday": "1978-07-23",
		"country": "US",
		"firstname": "Ivan",
		"personalid": null,
		"gender": "male",
		"created": "2021-02-22T15:58:38Z",
		"customFields": [
		      {
		        "value": "2",
		        "key": "cf_preferredlanguage"
		      }
		],
		"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": "[phone]",
		"provider": "passthrough",
		"ageVerification": false,
		"online": true,
		"id": "9c1cd25890ce9c3e439f8653ce26a1ab",
		"metrics": {
			"visitCount": 2
		},
		"email": "[e-mail]",
		"extraFields": {
			"extIds": {
				"prop2": "p2-9ad7.62d4",
				"prop1": "sf_484c",
				"id": "657ff9a9-62d4-484c-9ad7-fadc28605c30"
			}
		},
		"username": "9F04472C"
	},
	"organization": {
		"id": "52f09416a85fe315019cf3d93cc90a20"
	},
	"location": {
		"country": "IT",
		"address": "Pisa",
		"extId": "4234324234",
		"id": "ff80808160b03d96016a26aaefdb74e6",
		"tags": [
			"Office",
			"Europe"
		]
	},
	"event": {
		"type": "geo-leave",
		"nonce ": "bdf5e45deac3cdb8d1bbd5368390cdb ",
		"dwellTime": null,
		"timestamp": 1614009527
	},
	"geofence": {
		"metadata": [{
			"value": "casa",
			"key": "tipo"
		}],
		"name": "Emi_House",
		"geometry": {
			"coordinates": [
				10.517113,
				43.676046
			],
			"type": "Circle",
			"radius": 100
		},
		"id": "Emi_House",
		"extId": "casa",
		"tags": [
			"Emilia",
			"casa"
		]
	}
}

Fields description

Data structure	Description
"hotspot": { "id": "4fd9ca2340f699e2611d05f8b92772ff" }	hostspot id is the identifier of the access point in your Cloud4Wi account. Its value is not null only for the events that can be tracked at the access point level (e.g. WiFi signup, WiFi login). You can find the hotspot id in the URL path when viewing a specific Access Point in the Cloud4wi dashboard
"organization": { "id": "52f09416a85fe315019cf3d93cc90a20" }	organization id is the identifier of your Cloud4Wi account (sometimes referred to as "tenant id"). You can find your organization id in the Developers page
"location": { "country": "IT", "address": "Pisa", "extId": "4234324234", "id": "ff80808160b03d96016a26aaefdb74e6", "tags": [ "Emilia", "casa" ] },	Metadata of the location where the event occurred. "id": is the unique identifier of the location as referred to in the Cloud4Wi dashboard. You can find the location id in the URL path when viewing a location inside the Cloud4Wi dashboard. "country": country as specified in the full address "address": address filed of the location full address "extId": external reference id set for the location in the Cloud4Wi dashboard "tags": list of tags assigned to the location
"event": { "type": "geo-leave", "nonce ": "bdf5e45deac3cdb8d1bbd5368390cdb ", "dwellTime": null, "timestamp": 1614009527 },	Metadata of the event the webhooks refer to. "type": see the list of the events types at the top of the page (event types) "dwellTime": if the event has a duration, it is reported in this field in seconds; "timestamp": timestamp of the event in Epoch format "nonce": unique identifier of the event.
"contact": { "birthday": "1978-07-23", "country": "US", "firstname": "Ivan", "personalid": "45RTFG5676", "gender": "male", "created": "2021-02-22T15:58:38Z", "customFields": "customFields": [ { "value": "2", "key": "cf_preferredlanguage" } ], "optin": [{ "date": "2021-02-22T15:58:38.000Z", "name": "termsOfUse", "accepted": true, "id": 0, "type": "LEGACY", "version": "default" } }, "language": "en", "type": "guest", "civilStatus": null, "lastname": "Muccini", "marketing": true, "phone": "[phone]", "provider": "passthrough", "ageVerification": true, "online": true, "id": "9c1cd25890ce9c3e439f8653ce26a1ab", "metrics": { "visitCount": 2 }, "email": "[e-mail]", "extraFields": { "extIds": { "prop2": "p2-9ad7.62d4", "prop1": "sf_484c", "id": "657ff9a9-62d4-484c-9ad7-fadc28605c30" } }, "username": "9F04472C"	Metadata related to the contact record. "birthday": date of birth; "country": country where the contact signed up, based on the address of the location in format ISO-3166 "firstname": first name attribute "lastname": last name attribute "email": email address "phone": phone number in international format "civilstatus": salutation attribute ("Mr." "Mrs.", "Miss", null) "language": language of the user based on the language used on the Splash Page, in format ISO-639 "personalid": document number or personal id attribute as collected in the Splash Page "gender": gender ("male", "female", "other") "created": date the contact was created "marketing": legacy field to track consent to the default marketing consent "provider": method used to signup in the Splash Page ("passthrough", "cloud4wi", "kiosk", "sso", facebook", "google", "twitter", "instagram", "linkedin", "vkontakte", "pinterest", "foursquare", "sinaweibo", "baidu", "yahoo", "renren", "gigya", "apple", "qqweibo", "spid") "ageVerification": value of the age verification consent ("true", "false", "null") "online": WiFi connection status ("true", "false") "type": legacy file to track different types of users (discontinued) "username": username of the WiFi account "extIds": list of optional external identifiers tracked for the contact, usually used in case of bidirectional integration with eternal systems to track user Ids in case of SSO with enterprise IdPs "customFields": array of the custom fields as defined in the Cloud4Wi dashboard "visitCount": total number of WiFi logins of the user before the current event "optins": contains the list of consents collected. Each optin has the following attributes: "date": date the consent was collected "name": reference name of the consent. It could be the system default consents ("termsOfUse", "privacy", "mktgCommunications") or the name of the custom optins defined in the dashboard "accepted": if the optin has been accepted (true, false). Note that the default optins "termsOfUse" and "privacy" are always true in the system) "id": id if the opt-in; always zero for the default optins "type": "legacy" for the default optins, "custom" for the custom ones defined in the dashboard; "version": version of the consent; can be "default" or the value defined in the dashboard "customfileds": array of the custom fields define din the dashboard in the; the key assumes the value defined int eh dashboard and the value is the value provided by the user in the form