Webhooks

Webhooks let you receive automatic updates and notifications from the Unloc platform, enabling you to take your integration to the next level. By relying on the Unloc platform to report Access Event directly to an endpoint on your server, you can trigger actions based on users opening one of your Locks.

Use the Register Webook to endpoint specifying two parameters: the Lock you want to track Access Events for, 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/v2/projects/d45031c2-be07-4d20-adbe-4e51e6ad0fed/webhooks \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "trigger": "accessEvent",
  "url": "https://vandelay.ind/accessEvents",
  "lockId": "df50a61f-9e1f-4e1c-9e89-8395c908065a"
}
'

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/access-events every time a User you created a Key for makes use of it. The request body will contain a Access Event object with all the details of the event.

Access Event

A Access Event contains the data regarding the action performed, who triggered it, and the Lock they interacted with. Here’s an example of of an Access 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",
  "appUserId": "+12125552390",
  "userName": ""
}

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

With this data you can create a comprehensive logging system to track events, the different Locks of a Project, 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).

Access Event actions

The available Access Event actions are as follows:

Considerations

The Unloc app

In order to report a Access Event, the User’s Unloc app must have Internet access. Access 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 Access Event webhook requests. Other types, like Keys shared through the Unloc app are excluded from sending Access 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:[[email protected]](mailto:[email protected])/accessEvents

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

https://vandelay.ind/access-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/AccessEvents' \
--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",
  "appUserId": "+12125552390",
  "userName": ""
}’

Authentication Basic character limitations

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