Webhooks allow data such as name, email, date of birth, gender, sign up method, MAC address and more, to be pushed into your internal CRM systems in real time.
Benefits include:
- Get new data in realtime as soon as the event is triggered.
- Offer your customers a superior service. Using Webhooks, you are able to push visitors’ user data from Purple to your internal applications to enable a bespoke experience.
- Engage visitors with your brand. Having a live feed of your visitors’ data being pushed to your other CRMs gives you a more complete profile on each customer.
Add a Webhook
- At the company or venue level, navigate to the Portal's Management section from the left-hand sidebar and select Venues. Click the Webhooks tab at the top of the Venues page.
- You need to add and validate the destination URL (endpoint) you want the Webhook to push data to. Data is sent as a JSON object so you need to make sure your destination URL is capable of receiving the data. There is no limit on how many URLs you can validate.
- Once your URL is validated, navigate to LogicFlow in the portal and you will see a Webhooks Action Node. This needs to be set up in an 'Online' LogicFlow. After you’ve added your Start Node, place the Webhook Node in your flow and select your validated URL, then close your flow with the End Node. Validate and save.
- Next, you need to add your LogicFlow with the Webhook onto your Access Journey. From the Onboarding tab on the left-hand sidebar within the portal, click Access Journeys.
- From Access Journeys, select the LogicFlow tab and click ‘New logic flow’. Select the desired LogicFlow. Now, every time a user connects to your WiFi, their data will be pushed via the newly created Webhook.
Check our video guide showing the webhook creation process:
Webhook listener
To use Webhooks, you will need to have your own listener that receives and parses JSON in the format specified below.
The listener will receive POST requests from Purple with a JSON body. A typical request from Purple will be structured like this:
|
POST /your/url HTTP/1.1 Host: your.domain.com User-Agent: Purple Webhook Content-Length: 960 Accept-Encoding: gzip { "client": { "mac": "00-01-02-DD-03-EB", "userAgent": "Mozilla\/5.0 (X11; Linux x86_64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/99.0.4844.74 Safari\/537.36" }, "company": { "id": 99999, "name": "name", "uniqId": "uniq_ID" }, "session": { "authenticationTime": "2023-08-15T14:12:33+0000" }, "user": { "customFields": [], "dateOfBirth": "", "email": "webhook@test.com", "emailStatus": "", "firstName": "name", "gender": "F", "id": 123456789, "lastName": "surname", "locale": "en_GB", "mobile": null, "mobileCountry": null, "postcode": null, "provider": "Facebook", "title": null, "unsubscribed": true, "unsubscribedDate": null, "unsubscribedSource": null, "visitCountsForVenues": { "12345": 1 } }, "venue": { "id": 12345, "latitude": "53.481588", "longitude": "-2.046912", "name": "Test Venue", "uniqId": "vq-1ab123bc4e56e" } } |
The listener should be accessible via SSL, with a valid certificate. Data won’t be posted to non-SSL URLs. The listener should return a 200 response, and return the header wifiWebhookListener with a value of 1 (integer one) to verify it’s a real listener.
Data
Purple currently post the following data to Webhook listeners in JSON format:
| client | mac | MAC address of client interface |
| userAgent | User agent of client browser | |
| company | id | ID of company |
| name | Name of company | |
| venue | id | ID of venue |
| name | Name of venue | |
| longitude | Longitude of venue | |
| latitude | Latitude of venue | |
| session | authenticationTime | Date/time of authentication to WiFi |
| user | id | ID of user |
| User's email address | ||
| firstName | User's first name | |
| lastName | User's last name | |
| gender | User's gender | |
| provider | User's authentication provider (e.g. 'Form' or 'Facebook') | |
| visitCountForVenues |
This data may be expanded in future via the addition of new fields to the JSON, so your listener should be able to handle additions to the JSON schema without error.
Troubleshooting
The time between a user authenticating to the WiFi and a request being dispatched to a listener will typically be a few seconds. During maintenance or rare periods of very high load it’s possible this may take longer.
If a listener is unresponsive (takes longer than 10 seconds to respond) or returns an error message, requests are requeued and tried again after 3 hours. Purple will keep retrying the listener. Therefore after a period of downtime on your listener you will find old visits being delivered for up to three hours afterwards. Your listener will need to be able to handle this. This may also mean visits are delivered out of order.
After a prolonged period of unresponsiveness or returning a bad response, a Webhook will be automatically disabled for security reasons and will need manually re-verifying in the portal before it can be enabled again.
A request is dispatched to a listener on every authentication. It’s possible a user may ‘authenticate’ multiple times per visit, e.g. by clicking back in their browser, letting their phone idle, or even roaming from AP to AP. Listeners will need to manage this (e.g. if your use case involves sending a triggered email to your visitors, checks will be required so a given user is only emailed once per day instead of for every Webhook trigger).
Webhooks only POST basic data to listeners. The IDs returned for company, venue and user all match the IDs used on Purple’s Company API, though, so you can call back to the Company API to get more detailed information about a session or user.