Aiwifi can notify events to your application through the use of webhooks. Each link is cryptographically signed, so the request cannot be altered. If your brand receives a webhook, you can validate it to ensure it comes from Aiwifi and validate the event you have subscribed to.
Enable Events Webhook
To start receiving events for the webhook, you must perform some tasks as described below:
By default, Aiwifi sends all the events we have available when the communication setup is made. If you do not wish to receive all available events, Aiwifi needs to be notified about which events need to be sent. Currently, the events that can be sent are as follows:
- guest.connected (A user connecting to your brand)
- surveyAnswer.created (Response to a survey campaign on your brand)
- guest.interests (A user selecting interests)
Aiwifi needs you to provide a URL that is set up to receive an HTTP (POST) request, which will serve as the communication between us and your brand for the information sending. Aiwifi requires your application to respond with an HTTP status (200) when the communication with the webhook is received and you verify that the data is correct.
Signed request
To start sending information via webhooks, Aiwifi requires you to take into account the following considerations.
As mentioned above, Aiwifi needs your brand to provide a URL that can receive an HTTP (POST) request and respond with an HTTP status (200) when the communication is received and it is verified that the data is correct. Any other response, including an HTTP 301 or HTTP 302 redirection, will be considered a failure, and we will attempt to resend the same information. Aiwifi will provide your brand with a unique key for identification in our system. This key will be used to sign each request made to your URL. In each information send-out regarding any event, you will find in the request header the Aiwifi-Signature attribute, which is a hash of the information sent in the request.
To confirm that the information received through the communication URL is correct, you can do so in the following way:
phpCopy code$signature = hash_hmac('sha256', $payload, $secret);- $payload
- $secret
The PHP function hash_hmac generates an encrypted value through a key using the HMAC method.
Retry Policy
As mentioned earlier, if Aiwifi receives an HTTP status (200) from the communication with your URL, we will consider the webhook successful. However, if your application returns something different, it will be marked as a failed attempt, and we will resend the request again with the same information.
We will attempt to send the webhook up to 3 times. If we receive a response code that is not HTTP/200, or a timeout (of 3 seconds or more), after the third attempt, we will consider the webhook failed and will not resend that information again.
We will not disable the sending of events, no matter how many failed attempts we have. It will only be disabled if you inform Aiwifi that you no longer wish to receive the event shipments.
Connection events
This event aims to send information about the user who connects to your brand's portal. As mentioned earlier, each event includes generic information (information found in all events issued by aiwifi), as well as specific information for each type of event, as shown below.
In the event's data property, the personal information of the user who connected to your brand's captive portal is sent, subject to the following conditions:
- The data capture campaign set up by your brand allows capturing all user data; otherwise, only the information from the configured data will be sent.
- The user has already completed the required data, meaning that as the user becomes more familiar with your brand (makes recurring connections to your brand's portal), the necessary data will be obtained. Therefore, in the first instances, it is likely that the received data will be incomplete.
jsonCopy code{
"event_type": "guest.connected",
"event_id": "b8d057c59327541d7ec2104c0a9a255ad1997fb00831b9c6bbf09561e6d5cbd0",
"data": {
"user": {
"id": 1020,
"name": "John Doe",
"email": "[email protected]",
"phone": "+5255556789890",
"postalCode": "62577",
"birthdate": "1990-01-01",
"gender": "Male"
},
"brand": {
"id": 519,
"name": "Main"
},
"location": {
"id": 1,
"name": "Main Office"
},
"node": {
"id": 2,
"name": "Principal",
"mac": "AA:AA:AA:AA:AA"
}
}
}
Each of our events also sends information about the brand, location, and access point where the event took place.
Interests events
This event aims to send information about the interest campaign that your brand sets up (if your brand has 2 or more interest campaigns set up, you will receive this event for each one of them, when the customer selects interests).
In the event's data property, you will find information about the customer who has selected the interests (the customer attributes are subject to the configuration your brand has in the data capture campaign), as well as a list of the interests selected by the customer. Here is an example:
jsonCopy code{
"event_type": "guest.interests",
"event_id": "b8d057c59327541d7ec2104c0a9a255ad1997fb00831b9c6bbf09561e6d5cbd0",
"data": {
"user": {
"id": 1020,
"name": "John Doe",
"email": "[email protected]",
"phone": "+5255556789890",
"postalCode": "62577",
"birthdate": "1990-01-01",
"gender": "Male"
},
"interestItemsSelected": [
"Interest A",
"Interest B",
"Interest D"
],
"brand": {
"id": 519,
"name": "Main"
},
"location": {
"id": 1,
"name": "Main Office"
},
"node": {
"id": 2,
"name": "Principal",
"mac": "AA:AA:AA:AA:AA"
}
}
}
Each of our events also sends information about the brand, location, and access point where the event took place.
Survey events
This event is intended for sending information corresponding to a customer's response to your brand's survey campaign (it's important to note that if your brand has 2 or more active survey campaigns, you will receive this event for each of those campaigns).
In the event's data property, you will find information about the campaign the customer has responded to, such as the questions contained in the survey campaign, as well as the response to each of them. Here is an example:
jsonCopy code{
"event_type": "surveyAnswer.created",
"event_id": "b8d057c59327541d7ec2104c0a9a255ad1997fb00831b9c6bbf09561e6d5cbd0",
"data": {
"guest": {
"id": 1020,
"name": "John Doe",
"email": "[email protected]",
"postalCode": "62577"
},
"location": {
"id": 1,
"name": "Main Office"
},
"campaign": {
"id": 12,
"created_at": "2022-02-20",
"updated_at": "2022-02-20",
"questions": [
// Questions are listed here with their types and choices
],
"answers": [
// Corresponding answers to the questions listed above
]
}
}
}
The JSON structure shows the event_type, event_id, and data containing detailed information about the guest, the location of the event, the specific campaign answered, including questions, their types, possible choices, and the guest's answers to those questions.
Each of our events also sends information about the brand, location, and access point where the event took place.