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:

  1. 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
  2. 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
  3. 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 single domain integration

  1. Sign in to My Parakey, select your place
  2. Click on Settings then Integrations
  3. Scroll down to Webhooks and press Create new webhook

If you are creating an app (multi-domain integration)

  1. Sign in to My Parakey with your apps credential
  2. Click on Developer in the top many
  3. Scroll down to Webhooks and press Create new webhook

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
Hittade du svaret?