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.
Use the Advanced settings to add custom headers (e.g. Authorization: Basic ...) so you can verify that requests are coming from Parakey.
The fields available when creating a webhook depend on the resource type you're subscribing to. For event-log-specific options (devices, activities, allowed offset), see Receiving event logs.
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. Today only Event Logs are supported, so the body matches
GET /eventLogs/:id. The payload is currently always serialized as API version 1.0, regardless of the version you use elsewhere in the API.
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 the410is 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.