A webhook subscription sends LivionKey events to your own HTTPS endpoint as they happen, for example when a key is fetched or returned. You manage subscriptions in the API view, on the Webhooks tab. For payload formats and signature verification code, see the LivionKey webhooks developer reference.
Before you begin
Your organization needs API access. If you don't see API in the left menu, contact Livion Support.
You need a user role that can manage webhooks, such as Admin. If you don't see the Webhooks tab, ask an administrator of your organization.
Your endpoint URL must:
use HTTPS.
be reachable from the public internet. Private and internal addresses are rejected.
not contain a user name, a password, or a
#fragment.answer directly. Redirects are not followed.
Create a subscription
Click API in the left menu and open the Webhooks tab.
Click Create. If the list is empty, click Create webhook. The Add webhook subscription dialog opens.
Fill in the fields described below and click Save.
The Webhook signing secret dialog opens. Copy the secret, store it securely, and click Close.
The fields are:
Name — a name for your own reference. You can't change it later.
Endpoint URL — the HTTPS address that receives the events.
Organization unit — the unit whose events you want. Events from its sub-units are included. You can't change it later.
Events — one or more event types:
Key status — a key is fetched or returned, or is marked as not fetched or not returned.
Contract update — a contract is added or updated.
Code entered — a correct code (a PIN code, a return code, or an access code) is entered on a device.
Device alarm — a device alarm, such as a power or connection alarm, starts or ends.
The new subscription is shown in the list with the status Pending verification. It doesn't receive events until you verify the endpoint.
Store the signing secret
Every delivery is signed with the subscription's signing secret, which starts with whsec_. Your endpoint uses the secret to check that a delivery really comes from LivionKey.
IMPORTANT!
The secret is shown only once, in the Webhook signing secret dialog. After you close the dialog, only its last four characters are visible. If you lose the secret, delete the subscription and create a new one. The secret of an existing subscription can't be changed.
Verify your endpoint
Click the subscription in the list to open its details.
Click Send test.
LivionKey sends one signed test delivery for each selected event type. Test deliveries use placeholder values, not real data. When your endpoint answers every test delivery with a 2xx status code, the subscription becomes Active and starts receiving events. If a test fails, fix your endpoint and click Send test again.
For a subscription that is already active, Send test only checks the connection. It doesn't change the status.
Verify signatures
Check the signature of every delivery before you process it. Deliveries follow the Standard Webhooks specification: each request has the headers webhook-id, webhook-timestamp, and webhook-signature, and the signature is calculated with your signing secret. Use a Standard Webhooks library, or follow the instructions in the developer reference. Code examples are available for Node.js, Python, PHP, and Go.
Follow deliveries and retries
The list shows the Status and the Latest delivery result of each subscription. In the subscription's details, Latest delivery shows the most recent delivery: its status, the number of attempts, the event, and the delivery ID. Click Show payload to see what was sent. Only the most recent delivery is shown. There is no full delivery history.
Your endpoint must answer with a 2xx status code within 15 seconds. Answer first and process the event afterwards. Any other status code, a timeout, or a connection error counts as a failure, and LivionKey retries the delivery:
A delivery is tried up to 20 times over about 6 hours. The waits between attempts are 5 s, 15 s, 30 s, 1 min, 2 min, 5 min, 10 min, 15 min, and 20 min, and after that 30 minutes.
While a delivery is being retried, Latest delivery shows Delivery failing — retrying with the time of the next retry and the number of attempts so far.
Every retry has the same
webhook-idheader, so your endpoint can recognize a delivery that it has already processed.If you change the endpoint URL while a delivery is being retried, the next attempt goes to the new URL.
Edit, deactivate, or delete a subscription
Open the subscription's details and choose an action:
Edit — change the Endpoint URL or the Events. The name and the organization unit can't be changed. Changes to events take effect at once. A new endpoint URL is saved only if a signed test delivery for every selected event succeeds at the new URL. If the check fails, nothing is changed and the previous URL stays in use.
Deactivate — stop deliveries. The status changes to Disabled, and retries in progress stop. Events that happen while the subscription is disabled aren't sent later. To resume deliveries, click Activate. A subscription that has never passed a test can't be activated: use Send test instead.
Delete — remove the subscription permanently. Retries in progress stop.
Legacy webhooks
If Livion set up webhooks for your organization before self-service subscriptions were available, they are shown in the list with the status Legacy. They are read-only: you can't edit or test them.
To replace a legacy webhook with a self-service subscription:
Click the legacy row and click Create replacement. The dialog is pre-filled from the legacy receiver.
Save the subscription, store the signing secret, and verify the endpoint with Send test.
Make sure that your endpoint handles the new deliveries. Self-service subscriptions wrap each event in an envelope, which is a different format from legacy deliveries. See the developer reference.
Delete the legacy receiver. Until you delete it, both the legacy receiver and the new subscription deliver events.
Manage subscriptions through the API
You can also manage webhook subscriptions with LivionKey API v2 and a service account. Use POST /webhookSubscriptions to create a subscription, GET, PATCH, and DELETE to read, update, and remove subscriptions, and POST /webhookSubscriptions/{id}/test to send test deliveries. See the Webhook Subscriptions endpoints in the API reference.
To create a service account, see How to set up a service account for API communication. For API v2 basics, see LivionKey API v2: Mechanical keys and key contracts.