Webhook types
Unlock event — fires every time a user unlocks a lock. See Receiving event logs for the unlock-specific filters.
Batch completed — fires when every item in a batch operation has finished. See Receiving batch completions for the batch-specific filters and failure-handling guidance.
How to add a webhook
If you are creating a Manual 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.
On a Partner Integration you also choose which places the webhook applies to:
All places (auto-sync) (
autoSyncDomainsin the API) — recommended. The webhook automatically applies to every place that has added this integration, including ones that connect later. Without auto-sync you'd have to add a new webhook for every customer you onboard; with auto-sync you maintain a single webhook and route per customer on your side based on the domain in each payload.Let me select individual places — only the places you pick.
General settings
These apply to every webhook type (API field name in parentheses):
Name (
name) — displayed in the portal to make the webhook easy to recognise.URL (
url) — the HTTPS URL that receives the POST request.Places (
domains) — which places the webhook applies to (Partner Integration only, see above).API version (
payloadApiVersion) — payload schema for outgoing requests. Pinned to the version you pick at creation and only changes if you explicitly update this setting on the webhook.Custom headers (
headers) — extra HTTP headers Parakey sends with each request, useful for authenticating that the call originated from Parakey (e.g.Authorization: Basic ...). Values are stored as plain text in the portal, so don't put highly sensitive credentials here.
Request format
Each request is an HTTP POST to your URL:
Content-Type:
application/jsonUser-Agent:
Parakey-WebhookWorker/<version>Body: the JSON representation of the resource. The payload has the same shape as the corresponding GET endpoint for that entity, serialized using the webhook's configured API version:
Unlock event — matches
GET /eventLogs/:id.Batch completed — matches
GET /batches/:id.
Responding to a request
Your server should respond with a 2XX status code within 15 seconds of receiving a webhook request. If your server takes longer than that, or returns any non-2XX status (other than 410 Gone, see below), Parakey terminates the connection and considers the request a failure. Failed requests are retried according to the schedule below.
Treat a webhook as "we received your payload": acknowledge it quickly with 200 OK and then validate or process the payload asynchronously on your side. Do not return validation errors (400, 422, etc.) from your endpoint. Returning a non-2XX status causes the same payload to be resent, which usually isn't what you want for a payload your endpoint has already received.
If a request fails
If a request fails, it is retried up to 5 times (6 attempts total). The retry schedule, measured from the first failure, is:
after 1 minute
after 3 minutes
after 10 minutes
after 1 hour
after 4 hours
If all retries fail, the payload is dropped — it is not redelivered later.
Idempotence
Parakey delivers webhooks at-least-once, so in rare cases the same payload may be sent more than once. Your endpoint should be designed with this in mind: it should not make a difference to the final state of your system whether a payload is received on the first request or after several retries — this property is called idempotence. To deduplicate, use the id field in the payload, which is unique to each resource and stays the same across retries.
Disabling a webhook
A webhook can become disabled in three ways:
Your endpoint responds with
410 Gone. This acts as a "disable webhook" response. Parakey marks the webhook as disabled, so no new events will be dispatched to it, and the event that triggered the 410 is dropped (its remaining retries are cancelled).Repeated failures. A delivery is counted once per payload — failed retries of the same payload do not add to the count. Parakey automatically disables a webhook when:
10 deliveries fail with no successful delivery in the last 5 days, or
100 deliveries fail within a 24-hour window. A successful delivery resets the failure counter. A disabled webhook must be re-activated manually in the portal.
You delete the webhook. Any pending retries are abandoned and no further requests will be made for it.
This last point is useful if you want to make sure no in-flight retries hit your endpoint after a configuration change: delete the webhook first, then add a new one with the new URL or headers. Anything still queued under the old webhook will be abandoned, and only fresh requests will be made to the new one.