Webhooks are designated URLs which our system will respond to with the desired events to allow other systems to automatically receive updated information without having to make any HTTP requests to the Alocity system.
What are Webhooks?
Let's say that an access log was created in the Alocity system. Without webhooks, you would need to perform something called polling where you would be repeatedly requesting all the access logs for your account. In order to avoid this resource intensive process, we offer something called Webhooks. What the Alocity system does, is that every time a desired event happens (such as an access log being created), an event will be published. The address that the event is published to is a URL you have provided and this URL location is a webhook. What is published to this webhook is an object with the relevant information based on the event you asked to be notified about. The objects we pass are described for each event at the bottom of the page.
If you want to see what event objects look like, follow the instructions below on how to create a webhook and add events to it and use this site to listen for the webhooks. This site will make it easy to see the information we would be passing through your webhooks. Note: On that site, make sure you copy the URL they provide you for use in creating the webhooks, otherwise the information will not be published.
Viewing Webhooks
In order to manage your account webhooks, use your browser to navigate to the Alocity portal and, once logged in, navigate to the settings page by clicking on the gear icon at the top of the page. Once on the settings page, click on the Integration card and go to the Webhooks tab. There you will be able to add, edit, and deactivate your account webhooks.
Adding Webhooks
Webhooks can be created with or without any events attached to them and be edited later. Note that a webhook without any events will never be sent any information by the Alocity system.
Webhook Info Page
By clicking on a webhook in the list of account webhooks, you will be able to view and edit the information about the webhook such as the URL, the events it is listening to, and whether or not it is active.
Helpful Tip!
Marking a webhook as inactive using the Webhook Info page will allow you to temporarily deactivate a webhook without losing the attached events. To wipe all the events and deactivate an account webhook, you can click on the ... next to the webhook on the webhook list and select 'Deactivate'.
On the Webhook Info page, there is also a secret key listed. This secret key is very important, as all requests sent to your webhook will have this secret key included in the header of the request. This will help you to protect your system from requests not made by the Alocity system and ensure that messages your system receives have not been tampered with. For more detailed information, see here.
Adding Events To A Webhook
Adding events to an account webhook is made easy with an intuitive and easy to navigate page. All events are ordered in groups and the search bar at the top of the page makes it easy to find the events you are looking for.
Signed Header
Our signed header is made up of several parts of the request being combined and then hash mapped and converted to a base64 string to ensure security. The header to look for in the request is the header Alocity-Signature and it is made up of two parts: t:timestamp, in which the bolded part will be replaced with the timestamp of the message in epoch seconds, and sig:signature, in which the bolded part will be replaced with the hashed message signature.
The signature hash's input is made up of two parts in the following order (parentheses in this example should be ignored): timestamp.(event's payload). The secret key is used to create an HMACSHA256 hash object which is then used to hash the input. The final header sig value will be the base64 string of that computed hash.
Available Events
Below is a complete list of all of our available events that your webhooks will be able to listen to.
| Code | Payload Object | Description |
|---|---|---|
| accesslog.created | See in models. | Every time an access log is created and received in in our system from one of your devices, a message will be sent to the relevant webhooks. |
| door.healthcheck | { "serialNumber":string, "firmwareVersion":string, "databaseActive":boolean, "isConnected":boolean, "ipAddress":string } | Every time a health check response is received from the device or the connection state of a device changes, a message will be sent to the relevant webhooks. Note that the ipAddress will be an empty string if the message was published due to a connection state change. |
| door.state | { "serialNumber": string, "doorState":DoorStateType } | Every time the door state changes for any of your devices, a message will be sent to the relevant webhooks. See models for a definition for DoorStateType. |
| lock.state | { "serialNumber": string, "lockState": LockStateType } | Every time the lock state changes for any of your devices, a message will be sent to the relevant webhooks. See models for a definition for LockStateType. |
| user.card | { "userId": Guid, "action": string, "facilityCode": integer, "cardNumber": long } | Every time a card is created for one of your users, a message will be sent to the relevant webhooks. Current values for action is: • Created |
| user.face | { "id": Guid, "action": string } | Every time a face is added, updated, or deleted for one of your users, a message will be sent to the relevant webhooks. The Id is that of the user whose face this is. Current values for action is: • Enrolled • Updated • Removed |