Webhooks
Admin, API and webhooks (/admin/integrations). Needs module.integrations.
Register a URL and receive a signed HTTP callback when something happens.
Registering one
Section titled “Registering one”| Field | |
|---|---|
| URL | Where to deliver. Must be publicly reachable |
| Events | Which event types to receive. Empty means all |
| Enabled | Whether it is active |
A signing secret is generated when you create the endpoint. It starts
whsec_ and is used to verify that a delivery genuinely came from your
deployment.
There is a Test button. Use it before wiring anything up.
Verifying a delivery
Section titled “Verifying a delivery”Every request is signed with HMAC-SHA256 over the body, using your endpoint’s secret.
Verify the signature on every request. Your endpoint URL will eventually be known to somebody who should not be able to post to it, and the signature is the only thing distinguishing a real delivery from a fabricated one.
Compare using a constant-time comparison, not ==.
Events
Section titled “Events”The same events that drive the console’s realtime stream:
| Event | Fires when |
|---|---|
submission.created | A repair is lodged |
submission.status | Its status changes |
submission.vendor | It is sent to or updated by a vendor |
ticket.created | A ticket is raised |
ticket.status | Its status changes |
ticket.comment | A public reply is added |
ticket.merged | Two tickets are merged |
loan.assigned | A loan is issued |
loan.returned | A loan comes back |
loan.registered | A device is added to a pool |
loan.removed | One is removed |
loan.bulk | A bulk action runs |
loan.synced | A pool syncs from an MDM |
sla.breach | A target is missed |
monitor.up, monitor.down, monitor.alert | Monitor state changes |
backup.success, backup.failed | A backup completes or fails |
kiosk.request, kiosk.resolved | A kiosk assistance request is raised or resolved |
security.resolved | A security approval is decided |
automation.match | An automation rule matched |
Full list in events.
Building a receiver that behaves
Section titled “Building a receiver that behaves”Return 2xx quickly. Acknowledge and process asynchronously. A receiver that does thirty seconds of work before responding will time out.
Be idempotent. Assume you will occasionally see the same event twice. Key on the event and the record id.
Do not assume order. Two events fired close together can arrive in either order.
Log what you reject. A silently dropped delivery is a debugging session nobody enjoys.
The URL must be publicly reachable
Section titled “The URL must be publicly reachable”Plugboard blocks outbound requests to private, loopback and link-local addresses by default, so a webhook cannot be pointed at an internal host or a cloud metadata endpoint.
A self-hosted install that legitimately delivers to a LAN address needs:
ALLOW_PRIVATE_EGRESS=1Leave that off for anything multi-tenant. See the security model.
What to use them for
Section titled “What to use them for”Notify a chat channel. Post submission.created into a staff channel so the
desk sees kiosk bookings without watching the queue.
Feed an asset register. React to loan.assigned and loan.returned to keep
a finance system current.
Escalate breaches. sla.breach into whatever your school uses for
escalation.
Trigger your own automation. Anything the built-in automation rules cannot express, because they only run on creation and only do three things.
Realtime in a browser
Section titled “Realtime in a browser”For a browser client, use the server-sent event stream instead. Same events, no signature verification needed, because it runs inside an authenticated session.
Removing one
Section titled “Removing one”Delete the endpoint. Deliveries stop immediately.
Registering, testing and deleting are all recorded in the audit log.