Skip to content
plugboard.appRequest a demo

Build on it

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.

Choose Add webhook:

Field
Destination URLWhere to deliver. Must be publicly reachable. Use https://; plain http:// is accepted with a warning
Ticket departmentsWhich departments’ ticket events may be sent here. None means no ticket events
EventsWhich 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.

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.

Every delivery is a POST with a JSON body:

JSON
{
"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:

HeaderValue
content-typeapplication/json
x-plugboard-eventThe event type
x-plugboard-signaturesha256= and the hex HMAC-SHA256 of the body, keyed with the whole secret
webhook-idmsg_ and an id. The same on every attempt of one delivery
webhook-timestampUnix seconds when this attempt was sent
webhook-signaturev1, 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.

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.

A delivery is tried again when the receiver answers 408, 429 or any 5xx, or does not answer at all within 5 seconds:

After attemptNext attempt in
11 minute
25 minutes
330 minutes
42 hours
55 hours
610 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 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 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.

The same events that drive the console’s realtime stream:

EventFires when
ticket.createdA ticket is raised
ticket.statusIts status changes
ticket.commentA reply is added (internal notes need ticket.internal)
ticket.actionA ticket action is recorded, including a flow’s Notify the desk step on a ticket
ticket.merged, ticket.unmergedTickets are merged or split again
sla.breachA ticket or repair misses a target
submission.createdA repair is lodged
submission.statusIts status changes
submission.vendorIt is sent to or updated by a vendor
part.reorderA part needs reordering
automation.matchA flow’s Notify the desk step raised an alert about a repair or another record that is not a ticket
loan.registered, loan.removedA device is added to or removed from a pool
loan.assigned, loan.returnedA loan is issued or comes back
loan.bulkA bulk action runs
loan.syncedA pool syncs from an MDM
device.sync.partial, device.sync.failedA device sync finishes with gaps or fails
device.wipeA device wipe is requested
device.lapsA local admin password is read (needs device.laps.read)
fleet.healthFleet health changes
security.resolvedA security finding is resolved
monitor.up, monitor.down, monitor.alertMonitor state changes, or a directory sync alert
service.down, service.upA service goes down or starts having problems, or is working again (needs service.view)
service.statusA service’s status changes in any way, planned work included (needs service.view)
network.syncedA network sync finishes
backup.success, backup.failedA backup completes or fails
kiosk.request, kiosk.resolvedA kiosk assistance request is raised or resolved
identity.actionAn identity action is taken

Full list in events.

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.

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:

Terminal
ALLOW_PRIVATE_EGRESS=1

Leave that off for anything multi-tenant. See the security model.

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.

For a browser client, use the server-sent event stream instead. Same events, no signature verification needed, because it runs inside an authenticated session.

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.