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:
Event log 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.
Event log webhooks
A webhook subscribes you to unlock events on one or more doors. Whenever a matching event log is created, Parakey sends a POST to your URL with the event log as the body.
For the general mechanics of how webhooks behave (request format, retries, idempotence, disabling), see Webhooks.
Adding an event log webhook
Manual Integration: Settings → Integrations → Webhooks → Add.
Partner Integration: Developer → Webhooks → Add.
When creating the webhook you configure:
URL — where Parakey should send the event log.
Domains — which domain(s) the webhook applies to. Only available when adding a webhook on a Partner Integration. Manual Integrations are tied to a single domain, so the webhook automatically applies to it.
Devices — which doors should trigger the webhook. Leave empty to receive events from every door in the selected domain(s), or list specific doors to receive events only from those.
Allowed offset in minutes — see below.
Headers — custom HTTP headers Parakey sends with each request, useful for authenticating that the call originated from Parakey (e.g.
Authorization: Basic ...).
Allowed offset in minutes
Parakey locks work offline. A device that has no connectivity at the time of an unlock 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 allowed offset in minutes setting 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 offset, for example 5 or 10 minutes. A notification telling a host their guest arrived 6 hours ago is rarely useful, and a tight offset prevents that.
Audit logs, billing, occupancy reporting, critical check-in services: leave the offset at the default (unbounded). You want every event log eventually, even those uploaded after a long offline period.
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 offset setting.