Webhooks
Settings, API & webhooks (/admin/integrations), Webhooks section.
Needs integration.manage and module.integrations.
Register a URL and receive a signed HTTP callback when something happens.
This page is about Plugboard sending desk events out. For another app starting a Plugboard flow, or a flow starting a Power Automate flow, a Zap, a Make scenario or an n8n workflow, see external flows and hooks.
Registering one
Section titled “Registering one”Choose Add webhook:
| Field | |
|---|---|
| Destination URL | Where to deliver. Must be publicly reachable. Use https://; plain http:// is accepted with a warning |
| Ticket departments | Which departments’ ticket events may be sent here. None means no ticket events |
| Events | Which event types to receive. None chosen means every event its grants allow |
The review step shows what will be sent. A webhook’s grants are a snapshot of the permissions you hold when you save it: an event is delivered only when the webhook’s saved grants include that event’s permission. Permissions you are given later apply only after someone reviews and saves the webhook again (Edit events and grants). Campus limits apply too.
A signing secret is shown once, when you add the webhook. It starts
whsec_. Give it to the receiving system straight away.
Each webhook has a switch to turn deliveries on and off. Use Send a test
delivery from its menu before wiring anything up; a test sends a ping
event and is never retried.
URLs and secrets are write-only
Section titled “URLs and secrets are write-only”After you add a webhook, its URL and secret are never shown again in full.
A Power Automate sig or a Zap’s address is a credential in its own right, so
the list shows only the host and the last four characters of the URL, and the
last four characters of the secret. Error messages and stored replies have the
path taken out.
New signing secret in the menu issues a fresh secret, shown once. The old one stops working at once, so update the receiver before the next delivery.
What a delivery looks like
Section titled “What a delivery looks like”Every delivery is a POST with a JSON body:
{ "type": "ticket.created", "message": "Ticket created", "data": {}, "at": "2026-10-04T09:30:00.000Z"}data holds the record’s details and differs by event. Sample payloads,
under the webhook list, shows the body for any event with a copy button.
The headers:
| Header | Value |
|---|---|
content-type | application/json |
x-plugboard-event | The event type |
x-plugboard-signature | sha256= and the hex HMAC-SHA256 of the body, keyed with the whole secret |
webhook-id | msg_ and an id. The same on every attempt of one delivery |
webhook-timestamp | Unix seconds when this attempt was sent |
webhook-signature | v1, and the base64 HMAC-SHA256 of <webhook-id>.<webhook-timestamp>.<body> |
The last three follow Standard Webhooks.
For webhook-signature, the key is the base64-decoded part of the secret after
whsec_, which is what Standard Webhooks libraries expect.
Verifying a delivery
Section titled “Verifying a delivery”Verify webhook-signature with a Standard Webhooks library, or check
x-plugboard-signature yourself.
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 ==. With webhook-signature,
also reject a webhook-timestamp far from the current time, so a captured
delivery cannot be played back later.
Retries
Section titled “Retries”A delivery is tried again when the receiver answers 408, 429 or any 5xx, or does not answer at all within 5 seconds:
| After attempt | Next attempt in |
|---|---|
| 1 | 1 minute |
| 2 | 5 minutes |
| 3 | 30 minutes |
| 4 | 2 hours |
| 5 | 5 hours |
| 6 | 10 hours |
Attempt 7 is the last, about 18 hours after the first. Every attempt carries the
same webhook-id and body, freshly signed, so drop an id you have already
processed.
Other 4xx answers, redirects and addresses blocked by the egress guard are not retried. Changing a webhook drops its pending retries, and so does turning Integrations off.
A 410 turns the webhook off
Section titled “A 410 turns the webhook off”A receiver that answers 410 Gone is saying the address is retired. Plugboard
turns that webhook off, drops its pending retries, records it in the
audit log, and shows “Turned off: the receiver said this
address is gone.” Switch it back on once the receiving system is ready again,
or delete it and add the replacement address.
Delivery history
Section titled “Delivery history”Delivery history in a webhook’s menu lists its last 50 deliveries from the
past 7 days, with the status, how long it took and the first 2 KB of the reply.
A delivery can be sent again from there under the same webhook-id; a replay
is recorded in the audit log and is not retried by itself. Delivery bodies are
deleted after 7 days.
Events
Section titled “Events”The same events that drive the console’s realtime stream:
| Event | Fires when |
|---|---|
ticket.created | A ticket is raised |
ticket.status | Its status changes |
ticket.comment | A reply is added (internal notes need ticket.internal) |
ticket.action | A ticket action is recorded, including a flow’s Notify the desk step on a ticket |
ticket.merged, ticket.unmerged | Tickets are merged or split again |
sla.breach | A ticket or repair misses a target |
submission.created | A repair is lodged |
submission.status | Its status changes |
submission.vendor | It is sent to or updated by a vendor |
part.reorder | A part needs reordering |
automation.match | A flow’s Notify the desk step raised an alert about a repair or another record that is not a ticket |
loan.registered, loan.removed | A device is added to or removed from a pool |
loan.assigned, loan.returned | A loan is issued or comes back |
loan.bulk | A bulk action runs |
loan.synced | A pool syncs from an MDM |
device.sync.partial, device.sync.failed | A device sync finishes with gaps or fails |
device.wipe | A device wipe is requested |
device.laps | A local admin password is read (needs device.laps.read) |
fleet.health | Fleet health changes |
security.resolved | A security finding is resolved |
monitor.up, monitor.down, monitor.alert | Monitor state changes, or a directory sync alert |
service.down, service.up | A service goes down or starts having problems, or is working again (needs service.view) |
service.status | A service’s status changes in any way, planned work included (needs service.view) |
network.synced | A network sync finishes |
backup.success, backup.failed | A backup completes or fails |
kiosk.request, kiosk.resolved | A kiosk assistance request is raised or resolved |
identity.action | An identity action is taken |
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 takes more than 5 seconds to respond times out, and the delivery is tried again.
Be idempotent. You will see the same delivery more than once when a retry
crosses a slow acknowledgement. Key on webhook-id.
Do not assume order. Two events fired close together can arrive in either order, and a retry can arrive after a later event.
Log what you reject. A delivery dropped silently is hard to trace later.
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. Redirects are not followed.
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.
Start your own automation. A webhook can start a Power Automate flow or a Zap directly. For anything that should run inside Plugboard, with go-aheads, approvals and undo, build a flow instead.
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, and its delivery history goes with it.
Creating, changing, testing and deleting an endpoint, rotating its secret, replaying a delivery, and an endpoint turned off by a 410 are all recorded in the audit log. A deleted endpoint’s audit entry keeps the host it sent to.