Purple’s Webhooks allow you to receive data from Purple every time a user authenticates to your WiFi,with all of the basic details of the authentication (user, venue and device details).
This can be useful if you want to trigger real-time events or load data to your CRM without making repeated requests to Purple’s RESTful company API.
To use Webhooks, you will need to create your own listener that receives and parses JSON in the format specified below.
2. The listener
The listener will receive POST requests from Purple with a JSON body. A typical request from Purple will be structured like this:
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.
3. The portal setup
Once your listener is able to accept and process requests, you can proceed to the Company management page,and access the ‘Webhook’ tab. You will be able to add a new Webhook, with a name to identify the hook and the URL of your listener.
After adding your URL, click ‘Save and Validate’ and your listener will be tested to ensure it exists and returns a correct response (see 1. The listener above).
Once your Webhook listener is validated, the Webhook will be available for use from Purple’s LogicFlow:
This step is essential. Without a flow, your Webhook won’t be actioned. You can use the flow to only trigger hooks under certain conditions, or even to trigger different hooks with different conditions.
If you already use LogicFlow, you can simply add a Webhook action to your existing flow(s).
Finally, once your flow has been saved, you need to apply the flow to your journey:
After saving your access journey, login data will start being posted to your listener as users log in.
Purple currently post the following data to Webhook listeners in JSON format.
This data will 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.
5. Other considerations
Typically the time between a user authenticating to the WiFi and a request being dispatched to a listener will be just a few seconds, but during maintenance or rare periods of very high load it's possible this time may extend up to a minute or two.
If a listener is unresponsive (takes longer than 10 seconds to respond) or returns an error message, requests are re-queued and tried again after 3 hours. Purple will keep retrying the listener, so 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 mean visits are delivered out of order too.
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 - with some clients, vendors, configurations or under some circumstances 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, have checks to ensure a given user is only emailed once per day instead of on every Webhook trigger).
Although the 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, so you can call back to the Company API to get more detailed information about a session or user.
If you believe your Webhook isn't working, please contact firstname.lastname@example.org, but be sure to include as much detail as you can of the exact steps you've taken and the errors you've received, as well as including your listener code where possible.