Whenever a user unlocks a door in Parakey, an event log is created. If you want your system to react to these unlocks — for example to send a notification, register a check-in, or update a guest list — you have two options:
Unlock event webhooks — recommended. Parakey pushes each new event log to your server as soon as it's received.
Event log polling — your server pulls from the API on a schedule.
For most integrations, webhooks are the simpler and more responsive choice. Polling is useful when running a webhook endpoint isn't an option.
Unlock event webhooks
An Unlock event webhook subscribes you to unlock events on one or more locks. Whenever a matching event log is created, Parakey sends a POST to your URL with the event log as the body (same shape as GET /eventLogs/:id).
For the general mechanics of how webhooks behave (URL, places, custom headers, API version, retries, idempotence, disabling), see Webhooks. This article only covers the Trigger on options that are specific to unlock events.
Adding an Unlock event webhook
Manual Integration: Settings → Integrations → Webhooks → Add.
Partner Integration: Developer → Webhooks → Add.
Pick Unlock event as the webhook type. The wizard then shows a Trigger on step with the unlock-specific filters described below.
Trigger on
Events from these locks
Choose which locks should trigger the webhook:
All locks — every lock in the place, including locks that are added later.
Let me select individual locks — only the locks you pick.
Only available on Manual Integrations. Partner Integration webhooks always trigger on all locks in every place they apply to, regardless of whether the webhook uses All places (auto-sync) or specific places.
Ignore old unlock events
The Parakey app works offline. If the app has no connectivity at the time of an unlock it will queue the event log locally and upload it the next time it has a connection — which may be seconds, hours, or even days later. Each event log carries two timestamps:
timestamp— when the unlock actually happened on the device.createdAt— when the event log reached Parakey's backend.
The Ignore old unlock events setting (allowedOffsetInMinutes in the API) controls how stale an event log is allowed to be (the difference between those two timestamps) for the webhook to fire. By default this is unbounded — every event log is delivered, regardless of how late it arrives.
Pick the setting based on what you're building:
Live notifications (e.g. "guest arrived" push notifications): set a low limit, for example 5 or 10 minutes. A notification telling a host their guest arrived 6 hours ago is rarely useful, and a tight limit prevents that.
Audit logs, billing, occupancy reporting, critical check-in services: leave the setting at the default. You want every event log eventually, even those uploaded after a long offline period.
Limit how often the same lock and user can trigger
If the same user unlocks the same lock several times in quick succession, the webhook normally fires for each unlock. Turning on a debounce (debounceIntervalInMinutes in the API) delivers at most one webhook per (lock, user) pair within a time window you choose — useful to avoid flooding downstream systems with near-duplicate events.
The window is per (lock, user); other pairs are unaffected. After the window passes, the next unlock for that pair triggers the webhook again and starts a new window.
Event log polling
If a webhook isn't an option, you can poll the Event Logs endpoint on a schedule. We recommend an interval of 5 minutes or longer. If you need more responsive updates than that, use a webhook instead. The Parakey API uses ETags on every endpoint, so you can use conditional requests to skip work when nothing has changed.
Keep two values in your system:
lastETag— the ETag from the previous response.lastFetchedCreatedAt— the time you last polled. Note thatcreatedAtmay differ fromtimestamp, which is the time the door was actually unlocked (see above). On the first poll, usenew Date()(or any earlier point you want to start from).
Poll flow:
Call
GET /eventLogs?limit=1with theIf-None-Match: <lastETag>header.If the response is
304 Not Modified, nothing has changed — stop. Otherwise, save the new ETag and continue.Call
GET /eventLogs?startDate={lastFetchedCreatedAt}&orderBy=createdAt:DESC, process each event log, and setlastFetchedCreatedAt = new Date().
Because polling uses createdAt, event logs uploaded after an offline period are picked up the next time you poll — there is no equivalent of the Ignore old unlock events setting.