What is a Webhook?
As we conduct more of our business on the web, API events/triggers are growing in popularity - especially with modern SaaS applications.
With a webhook, you can program events in one SaaS application to trigger actions in another SaaS application in real-time. For example, say you've committed or merged a code into a Github staging branch. You may program that code to kick off an automated build and run tests via Travis CI, and if the build passes, it is then deployed on Heroku, notifying everyone via Slack. In the API world, this practice of pushing information from one application to other applications in real-time is called a Webhook.
Webhooks are “user-defined HTTP callbacks" or "HTTP Push API.” They are a way for an app to provide other applications with real-time information. A webhook sends the data to other applications the moment it happens.
With typical polling, APIs need to poll for data very frequently in order to gather it real-time. This is called Polling Madness. The constant polling of an endpoint is wasteful in terms of resources. Webhooks help prevent polling madness, making them much more efficient for both the provider and consumer.
Genea supports webhooks which allow you to receive specific Genea event data in real-time at a specified URL. A few examples include:
Access Events such as
Access Granted Events
Access Denied Events
Anti-Passback Violation Events
Door Contact - Forced Open
Door Contact - Secured (Previously Forced Open)
Door Contact - Held Open is Enabled
Door Contact - Forced and Held Open
Control Point Events
Monitor Point Events
Interface Panel Events
Schedule Events
Remote Operations and
.... many more
Audit Events such as
Created / Updated / Deleted / Installed / Uninstalled events for any resource. (i.e User, Card, Access Group, UserLocation, Controller, Door, etc)
You can use event data to roll your own integration. For example, you can:
Log everything in your own central logging system.
Turn off the alarm system when the first person arrives in the morning with a successful access granted event.
Log office arrival entries for all your users into a time-tracking software.
Start brewing the coffee on your smart coffee machine upon the first user arrival in morning...and list goes on!
How To Configure Webhooks With Your Genea Dashboard
Navigate to the Global View, select the 'Integrations' menu, and locate 'Webhooks' in the Roll Your Own section. Ensure that logged-in users must have Admin access to enable/modify Webhook configuration.
Click 'Manage' to go to the detail page
You will now see the list of endpoints. You can add multiple endpoints for different purposes.
Click on the "Add" button to add a new endpoint and fill the required fields
Webhook Name : < A desire descriptive name>
Endpoint URL: <Your Target Application HTTPS URL>
Version : If you desire to use the latest payload select v3. Please see the below table for more details.
Version | Hardware | Event Supported |
v1 | VertX | All ACCESS and AUDIT events |
v2 | Mercury | All ACCESS and AUDIT events |
v3 | Mercury & VertX | Mercury supports all AUDIT and ACCESS events with an updated payload. VertX maintains a consistent payload structure same as version v1 across all AUDIT resources and ACCESS events, with the exception of user-related AUDIT resources (such as User, Location, User Location, etc). If hardware is distributed across different locations, it is essential to use webhook version v3. Other versions will not be supported when there is a combination of Mercury and VertX hardware at different locations (i.e., one location with Mercury and another with VertX). |
Delivery retires : If you would like 100% delivery then enable the delivery retries. Delivery retries will be initiated in the event of receiving a status code other than HTTP 200 OK from the sent webhook.
After you save the details, it will return you back to the list page. If you desire to use a secret key then go to actions and click edit
You will now see a "Reveal Key" button to check the key
We can now also integrate with products like Data dog. User wil be able to add Custom header and Custom body for the same.
Details to be added in Header and Body:
Custom Header: API key details, this can be fetched from the API doc
Custom Body: Anything that you would like to add to the body can again be fetched from the API document
This integration is not just for data dog, it will help us with any other integration with such products.
Webhook Security With Payload Signature
Genea uses a provided secret token to create a hash signature for each payload to ensure that the request is actually coming from us. This hash signature is passed along with each request in the headers as a X-Sequr-Signature. The signature is calculated as follows:
X-Sequr-Signature : 'sha1=' + OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), ENV['SECRET_TOKEN'], payload_body)
On your side, you will use your secret key, calculate the signature from the received payload, and compare both signatures - one received from your Genea webhook in the HTTP headers, and the one calculated on your side.
You can view a sample implementation here.
Notes:
Please make sure you have a valid SSL for your target URL.
Genea webhooks anticipate HTTP 200 OK response; otherwise, it will initiate up to three retry attempts, provided you have enabled delivery retries.
The payload content type is restricted to application/json exclusively.
To view a sample payload, please take a look at our Public API documentation for webhooks available here.
IP Address for Webhook Calls to Enable Whitelisting
If your firewall blocks the incoming webhooks, then you may need to configure rules to add the below IP address to the whitelist:
IP Address for Genea's webhook calls for production: 34.205.175.141
If you need assistance setting up a webhook for your organization, or if you'd like to share feedback, you can always reach the Genea Support Team via live chat in your Genea web app. You can also contact us via email at acsupport@getgenea.com.