Events and webhooks
See what LibrePortal did, and have it tell another service the moment it happens with a signed webhook.
On this page
LibrePortal keeps a log of what it does: apps installed, removed, started and stopped, sign-in changes, and people and groups added, changed or removed. A webhook sends each of these to an address you choose, so another service can react straight away.
Only what LibrePortal itself does is an event. A container that crashes, or one you stopped with docker stop, is not.
Reading the log#
libreportal events list --since 1d
libreportal events list --type app. --json
--since takes 15m, 2h, 1d, a date and time, or id:<number> for a service that polls and picks up where it left off. --type is the start of an event name, such as app. or person.created. A service with an events:read access key can read the same log.
Adding a webhook#
Go to Admin → Notifications and use the Webhooks card, or run:
libreportal events webhook add https://example.org/hook --types app.,person.
You choose which kinds to send: apps, people, groups, or all. The signing secret is made for you and shown once. An address on this server, your home network or the VPN needs one extra confirmation (--allow-private), so a webhook cannot be pointed at your own network by accident.
Use Test on a webhook to send one signed test event and see what came back. Each webhook can be switched off or removed; removing it also removes its secret and anything waiting to be sent.
What arrives#
Each delivery is a POST with the event as JSON and these headers:
X-LibrePortal-Event: the kind of event.X-LibrePortal-Delivery: an id that is the same on every retry.X-LibrePortal-Timestamp: when it was sent.X-LibrePortal-Signature:sha256=followed by an HMAC-SHA256 of the timestamp, a dot, then the body, made with the webhook's secret.
Check the signature before you trust a delivery. A failed delivery is tried again after 1 minute, 5 minutes, 30 minutes, 2 hours and 12 hours, then given up.