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.

Sequr supports webhooks which allow you to receive specific Sequr 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 Sequr Dashboard

  • Go to your Sequr Dashboard and log into your admin account.  
  • Click on the 'Integrations' tab and look for the 'Webhooks' integration.

  • Click 'Install' and specify the following values:

Your Webhook URL: <Your Target Application URL>
Your Secret for Signature :  <Sequr generated secret>

Note: Make sure you use a HTTPS URL only for your target webhook URL. 

Webhook Security With Payload Signature

Sequr 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 Sequr 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.
  • Sequr webhooks expect 200 OK in return, otherwise it will retry 3 times within the interval of 10 seconds.
  • Payload content type would be application/json.

Here is sample payload for an 'Access Granted' event: 

{
   "id":"59183",
   "property":{
      "id":86,
      "name":"MTec",
      "address_line1":"6655 Tulip Garden, Alpharetta, GA 30004, US",
      "address_line2":"Suite 108",
      "city":"Alpharetta",
      "state":"GA",
      "zip":"30004",
      "phone":"4702823126",
      "timezone":"America/New_York",
      "latitude":34.1317,
      "longitude":-84.256
   },
   "event_time":"2017-10-25T16:11:42.000Z",
   "event_type":"ACCESS",
   "event_action":"A_GA",
   "event_message":"Grant Access",
   "event_note":null,
   "event_hw_info":{
      "Interface Address":"0",
      "Side 0(L)/1(R)":"1",
      "Card Unique ID":"1210",
      "mac":"00:06:8E:02:04:ED"
   },
   "actor":{
      "type":"PERSON",
      "property_user_id":"1312",
      "property_user_role":"USER",
      "user_id":"1214",
      "user_name":"Allison Joseph ",
      "user_email":"mishi+41@sequr.io",
      "user_avatar_url":"https://dev-images.sequr.io/a6d29ce.png"
   },
   "reader":{
      "id":24,
      "site_location":"Exit Door",
      "door_status":"CLOSE",
      "model":"iCLASS® R10"
   },
   "interface":{
      "id":26,
      "site_location":"Office 1",
      "type":"a",
      "model":"VertX V100"
   },
   "controller":{
      "id":17,
      "site_location":"Main Office",
      "mac":"00:06:8E:02:04:ED",
      "model":"Main Office",
      "status":"ONLINE"
   },
   "card":{
      "id":1210,
      "property_user_id":1312,
      "type":"KEYCARD",
      "status":"ACTIVE",
      "card_number":"8988970372",
      "start_date":"2017-10-24",
      "end_date":"2017-10-28"
   },
   "created_at":"2017-10-25T16:11:49.716Z"
}

If you need assistance setting up a webhook for your organization, or if you'd like to share feedback, you can always reach the Sequr Support Team via live chat in your Sequr web app. You can also contact us via email at support@sequr.io.

Did this answer your question?