Skip to main content

Track unlocks using webhooks

Whenever a user unlocks a door, Kisi will store it as an event, along with information like who unlocked, which door, when, and with what credentials. You can find this information in the admin dashboard, under Unlock history. But you can also pull the unlock events by setting up a webhook URL for Kisi. The webhook can instantly notify your application of door unlocks by posting the data in a JSON document to the webhook URL that you specify.

Set up the integration​

  1. Sign in to Kisi
  2. Under Settings, click on Integrations
  3. Click on Add Integration
  4. Define the name of your new webhook integration, e.g. Kisi unlocks
  5. Open the Type dropdown and select Event Webhook
  6. In the URL field, enter the destination URL
  7. [Optional] If a signature key is provided, it will be used to calculate an HMAC-SHA256 digest of the JSON in the body of the HTTPs request. The digest is then sent along with the X-Signature header
  8. Under Event types, select lock.unlock
  9. Click Save. The integration will take effect immediately.
tip

You can test your webhook integration using free tools, such as Webhook.Site. Add the URL provided there to the URL field of your integration, then navigate to Doors and unlock one of them. You should see the incoming request in your Webhook.Site instance.

Sample webhook payload​

{
  "uuid": "d7cf0237-a492-4e5d-b20c-f58fc3ef4eff",
  "actor_type": "string",
  "actor_id": 0,
  "actor_name": "string",
  "object_type": "Lock",
  "object_id": 0,
  "object_name": "string",
  "organization_id": 0,
  "place_id": 0,
  "success": true,
  "type": "lock.unlock",
  "error_code": null,
  "error_message": null,
  "created_at": "2022-10-06T13:49:35Z"
}
  • Object: the Kisi resource that has been interacted with
    • object_type - e.g. "Lock"
    • object_id - the respective lock id, e.g. 1234
    • object_name - the respective object's name in Kisi, e.g. `"Main Entrance"
  • Actor: the user acting on the object
    • actor_type - this parameter may return three different values:
      • User - e.g. when the door was unlocked by a known user
      • null - e.g. when the door was unlocked via a request to exit button, hence the user is not known
      • GroupLink - e.g. when the door was unlocked via an access link
    • actor_id - the ID of the actor_type, e.g. user ID or access link ID
    • actor_name - the username

Response​

{
  "user": {
    "id": 0,
    "email": "user@example.com",
    "name": "string"
  }
}
info

Webhook endpoints may sometimes receive the same event multiple times. To prevent duplicate event notifications, we recommend that you make your event handling idempotent. For example, you can log the events you’ve processed, and then not process the already logged ones.

Rate limits​

We are not implementing any rate limits for events sent via webhooks.

Idempotency​

Webhook endpoints may sometimes receive the same event multiple times. To prevent duplicate event notifications, we recommend that you make your event handling idempotent. For example, you can log the events you’ve processed, and then not process the already logged ones.

Frequently used webhook events​

  • lock.opened - track when doors are physically open
  • lock.unlock with "success": false - track failed unlocks
  • login.create - track new logins