If you want to be notified or update your system every time a user unlocks a door you can use event log polling. The Parakey API uses ETag headers to indicate if any changes have been made on every endpoint, and we can use this ETag for event polling. By using the If-None-Match header on your request you will receive an "HTTP 304 Not modified" response if nothing has changed.
So to do EventLog polling setup a script that runs in an interval (we do not recommend an interval of less than 60 sec).
You need to keep track of two variables in your system:
lastETag- Always save the last received ETag to use in If-None-Match header.
lastFetchedCreatedAt- This is used to guarantee you will get all event logs since your last poll. Please be aware that createdAt might be different from the timestamp you receive in the EventLog. The timestamp is always the time the actual door was unlocked. For the first request before you set lastFetchedCreatedAt you can simply use new Date() (and you will only receive updates starting from now, or any date when you want to start reading from)
Then implement the following event poll flow:
Set up the polling on the Get EventLogs endpoint with
?limit=1
- First time just save the ETag and move on
- Every following request send the if-None-Match header with the ETAG
If you receive an "HTTP 304 Not modified" response.
- Nothing has changed and you do not have to continue, for every other HTTP response save the ETag and keep going
Otherwise, do a request on Get EventLogs using
?startDate={lastFetchedCreatedAt}&orderBy=createdAt:DESC
- Save lastFetchedCreatedAt = new Date();
- Loop through each EventLog and update your system.
Webhooks
You can also subscribe to webhooks. A webhook will perform a POST with each event log to a URL you specify. The payload will be the same data as an individual event log (in the api docs).
How to add a webhook
If you are creating a Custom Integration:
Press Settings then Integrations.
In the section Webhooks, press Add.
If you are creating a Partner Integration:
Press Developer in the top menu.
In the section Webhooks, press Add.
Authentication for webhooks
We recommend using authentication to protect your endpoints to make sure they are coming from our API. You can do this by adding Basic Authentication headers, you find custom headers in the Advanced settings for each webhook.
Limitations
A webhook will retry 5 times if the call fails
The last retry will be ~20 after the first call failed