Key Events Webhook

Webhooks are a great way to integrate logging features or even further integrations to your solution by relying on the Unloc platform to report Key Events directly to an endpoint on your server.

You can use the Register a new Key Events webhook on a Lock specifying 3 parameters: the Lock you want to track Key events for, it’s Lock Holder, and the webhook URL you want to get the reports at.

Here's an example webhook registration request:

curl --request POST \
     --url https://api.unloc.app/integrators/v1/lock-holders/d45031c2-be07-4d20-adbe-4e51e6ad0fed/locks/c0f3aed0-2a7e-4de5-a0ff-3bfc22bfbeef/key-events/webhooks/ \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --data '{
     "webhookUrl": "https://vandelay.ind/key-events"
}'

Notice that you're only required to send a webhookUrl parameter in the request body.

The Unloc platform will perform an HTTP POST request to https://vandelay.ind/key-events every time a User you created a Key for makes use of it. The request body will contain a Key Event object with all the details of the event.

Key Event

A Key Event contains the data regarding the action performed, who triggered it, and the Lock they interacted with. Here’s an example of of a Key Event:

{
  "id": "ae832e61-c8fa-4ed9-8196-61210cb4207b",
  "action": "unlocked",
  "created": "2022-01-01T10:35:24.083Z",
  "keyId": "3f97fafb-1b6a-42d0-85fa-ae2ef338cc45",
  "lockId": "c0f3aed0-2a7e-4de5-a0ff-3bfc22bfb6ef",
  "lockName": "North gate",
  "userId": "+12125552390",
  "userName": ""
}

You can also get the last 30 days of Key Events on a Lock using the Get Key events on a Lock endpoint.

With this data you can create a comprehensive logging system to track events, the different Locks of a Lock Holder, an access control system, or automations, like switching the corridor lights on, or even calling an elevator whenever the main entrance is opened (would require an integration with another system).

Key Event actions

The available Key Event actions are as follows:

Considerations

The Unloc app

In order to report a Key Event, the User’s Unloc app must have Internet access. Key Events that are fired while the Unloc app is offline, will be reported whenever the Unloc app obtains Internet access again.

Keys

Only Keys created by an Integrator will trigger Key Event webhook requests. Other types, like Keys shared through the Unloc app are excluded from sending Key Event webhook requests.

The webhook URL

HTTPS

The domain of the webhook URL Must use SSL/TLS, meaning the URL must begin with https.

Authentication

The webhook URL can contain basic authentication. If used, the URL should include the user name and password like this:

https://myuser:mypassw[email protected]/key-events

When a Key Event is recorded, the Unloc platform will perform an HTTP POST request to:

https://vandelay.ind/key-events

With an Authorization header:

Authorization: Basic bXl1c2VyOm15cGFzc3dvb3Jk
Where bXl1c2VyOm15cGFzc3dvb3Jk is the base64 encoded string myuser:mypasswoord.

Here is an example of a request coming from the Unloc platform towards your webhook endpoint using basic authentication:

curl --location --request POST https://vandelay.ind/key-events' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bXl1c2VyOm15cGFzc3dvb3Jk' \
--data '{
  "id": "def32263-a884-aed0-f167-f1a1ccbd297a",
  "action": "locked",
  "created": "2022-01-01T10:40:00.013Z",
  "keyId": "3f97fafb-1b6a-42d0-85fa-ae2ef338cc45",
  "lockId": "c0f3aed0-2a7e-4de5-a0ff-3bfc22bfb6ef",
  "lockName": "North gate",
  "userId": "+12125552390",
  "userName": ""
}’

Authentication Basic character limitations

Please refrain from using the reserved characters specified in RFC3986 for your user or password:
: / ? # [ ] @ ! $ & ' ( ) * + , ; =