What is a Webhook?

How To Configure Webhooks With Your Genea Dashboard

Webhook Security with Payload Signature

IP Address for Webhook Calls to Enable Whitelisting

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 Granted Events

  • Access Denied Events

  • Anti-Passback Violation Events

  • Created / Updated / Deleted events for any resource 

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

  • Go to your Genea Dashboard and log into your admin account.  

  • In the location view, click on the 'Integrations' menu and look for the 'Webhooks' under the Roll your own section.

  • 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 else select v1 for VertX hardware and v2 for Mercury hardware

Delivery retires : If you would like 100% delivery then enable the delivery retries

  • 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

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 expect 200 OK in return, otherwise it will retry 3 times within 1 minute.

  • Payload content type would be application/json.

Here is a sample payload for an 'Create Card' event for v1 and v2 :

{
"uuid":"15582781",
"event_time":"2021-10-01T12:36:40.264Z",
"event_type":"AUDIT",
"event_action":"CREATED",
"event_message":"Created Card 4542231 for Aaron Anderson",
"event_note":null,
"additional_info":null,
"location":{
"uuid":"ce0ad974-7d4d-42a4-af09-b6d3222f99c1",
"name":"Genea Plaza",
"address_line1":"19100 Von Karman Ave Suite 550 Irvine, CA 92612",
"address_line2":"Suite 500",
"city":"Kamrej",
"state":"GJ",
"zip":"394185",
"phone":null,
"timezone":"America/New_York",
"latitude":21.2757,
"longitude":72.9659
},
"actor":{
"type":"PERSON",
"user_location_uuid":"8d4067c0-c827-46d0-84ed-8724f224dbec",
"user_location_role":"ADMIN",
"user_uuid":"e48d7bbe-cca1-43ef-b48e-8030ec07e74b",
"user_name":"Anna Williams",
"user_email":"mercury.single@grr.la",
"user_avatar_url":"https://stage-genea-ac.imgix.net/avatar/user/original/e48d7bbe-cca1-43ef-b48e-8030ec07e74b_1615202698.jpeg"
},
"created_at":"2021-10-01T12:36:40.333Z",
"audit_resource":{
"id":null,
"uuid":"9c5589a8-2b12-427b-88f8-714d3095ed3c",
"name":"4542231",
"type":"CARD"
}
}


Here is a sample payload for an 'Create Card' event for v3 :

{
"actor":{
"type":"PERSON",
"uuid":"e48d7bbe-cca1-43ef-b48e-8030ec07e74b",
"name":"Anna Williams",
"email":"mercury.single@grr.la",
"mobile_phone":"+134324543",
"department":"Sales",
"employee_number":null,
"cost_center":"USA"
},
"resource_type":"CARD",
"resource_action":"CREATED",
"event_time":"2021-10-01T12:39:40+00:00",
"resource":{
"uuid":"381c7add-853a-480a-a5b1-650725165cb9",
"card_number":"545423",
"type":"KEYCARD",
"status":"ACTIVE",
"user_uuid":"a121f8fa-b270-4db0-b2ba-0af3fc890200",
"badge_type_uuid":"095a5d45-1640-408f-bfa9-385caa018276",
"activation_time":"2021-10-01T12:39:40+00:00",
"deactivation_time":"2021-11-30T12:39:40+00:00",
"created_at":"2021-10-01T12:39:40.309Z"
}
}


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.

Did this answer your question?