Webhooks are designated URLs which our system will respond to with certain events to allow other systems to automatically receive information about certain events occurring in the Alocity Selfie system.
What are Webhooks?
Let's say that an invitation was created in the Alocity Selfie system. Without webhooks, you would need to perform something called polling where you would be repeatedly requesting all the invitations for your account. In order to avoid this resource intensive process, we offer something called Webhooks. What the Alocity Selfie system does, is that every time a desired event happens (such as an invitation 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 certain events in our system. 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 and don't already have a webhook receiver set up, use this site to create a webhook URL and use the endpoint Create Webhook to create your webhook if you don't already have one or Update Account Info and Webhook URL to update the URL of your existing webhook. Once that is done, the website will listen for the webhook events. 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.
Once your webhook is created, support will provide you with a secret that you will use for authenticating information being published to your webhook URL. This secret is very important, as all requests sent to your webhook will have this secret included in the header of the request. This will help you to protect your system from requests not made by the Alocity Selfie system and ensure that messages your system receives have not been tampered with. For more detailed information, see below.
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.
The basic form that will be sent in every webhook response is as follows.
{
"Id": "124280c5-f218-4c9f-b3c3-b3e85f23889f",
"AccountId": "08ddbd25-0af3-4732-8920-65ffc95d1426",
"OrganizationId": "bdfa8ad6-e5ee-4293-a75f-a4fd0df5895b",
"CorrelationId": "038ba158-f008-4b70-8384-55934359eb69",
"EventCode": "InviteSent",
"Payload": null,
"TimeStamp": 1677170830
}
| Field Name | Type | Description |
|---|---|---|
| id | Guid | The Id of the event from our system. |
| accountId | Guid | The account Id of the your account. |
| organizationId | Guid | The Id of the organization from which the event occurred. |
| correlationId | Guid | The correlation Id provided. |
| eventCode | string | The event code. |
| payload | object | The object, if any, that will be provided with the event. |
| timestamp | long | The Unix timestamp (in seconds) of the event. |
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 |
|---|---|---|
| InviteSent | None | An invitation was created and successfully sent to the provided email and phone number. |
| Template | { "template": string } or { "template": string, "image": string } | The template for a face was successfully generated and is being sent to your system. The image is available based on account level configuration and it is the image used for generating the template |
| InviteInvalid | { "pinAttempts": integer } or { "photoAttempts": integer } | Either the number of pin attempts or photo attempts has exceeded the maximum of 3 and the invitation is no longer valid. |
| FaceQualityFailures | { "photoAttempts": integer } | A low quality photo was used to register the face and the photo was rejected. The current number of photo attempts will be sent. |
| PinFailures | { "pinAttempts": integer } | The pin entered was invalid. The current number of pin attempts will be sent. |
| PinOk | None | The pin was entered correctly. |
| FaceMatched | { "subjects": array of strings } | The face in the photo provided matched with some other faces in the organization. The subjects field will contain the user Ids of all the users who the face matched with. |