Events
One set of events drives three things: the toasts in the console, the realtime stream, and outbound webhooks.
The envelope
Section titled “The envelope”| Field | |
|---|---|
type | The event type, listed below |
message | A short human-readable line, shown in the toast |
permission | The permission a person must hold to be sent this event |
siteId | The site the event belongs to, where it belongs to one |
sticky | Whether the toast stays until dismissed |
data | Structured payload: ids, loan number, person name |
at | ISO timestamp |
Repairs
Section titled “Repairs”A repair is a submission in the event types.
| Type | Fires when |
|---|---|
submission.created | A repair is lodged. Sticky when lodged by a client |
submission.status | Its status changes |
submission.vendor | It is sent to, or updated by, an external repair vendor |
part.reorder | A part in the parts catalogue reaches its reorder level, through a repair that used it or a change to its stock or level. Sticky |
Tickets
Section titled “Tickets”| Type | Fires when |
|---|---|
ticket.created | A ticket is raised |
ticket.status | Its status changes |
ticket.comment | A reply or an internal note is added. The note version is sent only to people who can read internal notes |
ticket.action | An action run on a ticket sends the desk a notice |
ticket.merged | Two tickets are merged |
ticket.unmerged | A merged ticket is separated again |
ticket.escalated | A ticket is escalated or de-escalated to somebody. Sent only to the person it is handed to, and opens the ticket |
| Type | Fires when |
|---|---|
loan.assigned | A loan is issued |
loan.returned | A loan comes back |
loan.awaitingErase | A returned loan device is held until it is erased, because its loan group holds for erase. Sent only to people with device.wipe.request at the loan’s campus; not sticky. Names the loan, never the borrower |
loan.registered | A device is added to a pool |
loan.removed | A device is removed |
loan.bulk | A bulk action runs |
loan.synced | A pool syncs from an MDM smart group |
Devices
Section titled “Devices”| Type | Fires when |
|---|---|
device.sync.partial | A fleet sync from an MDM finishes, but some devices could not be recorded |
device.sync.failed | A fleet sync from an MDM fails. Sticky |
device.wipe | An erase is requested for a device, and again when it is sent. Sticky, to everyone who can see the device |
device.laps | A local administrator password is read. Sticky, and sent only to people with device.laps.read |
fleet.health | A fleet health scan finds devices that need attention |
Service quality
Section titled “Service quality”| Type | Fires when |
|---|---|
sla.breach | A response or resolution target is missed. One shot per item |
automation.match | A flow’s Notify the desk step raised an alert about a repair or another record that is not a ticket |
Monitors
Section titled “Monitors”| Type | Fires when |
|---|---|
monitor.up | A monitored service recovers |
monitor.down | It goes down |
monitor.alert | An alert threshold is reached, or a directory sync needs attention. Also, when a monitor goes down, the changes made near it in the last 72 hours, sent only to people with change.view |
service.status | A service’s status changes in any way, planned work starting or ending included. Sent to people with service.view to keep the desk current, without a toast of its own, because its monitors raise their own. Its data carries the service’s id, its status and the status before, from |
service.down | A service reads Down or Having problems after reading anything else. Sent the same way, without a toast. Its data carries serviceId, name, status and from |
service.up | A service that was Down or Having problems reads Working. Sent the same way, with the same data |
dns.recordChanged | A watched DNS record changes |
dns.expiring | A watched domain or certificate is about to expire |
network.synced | A refresh from the network connectors finishes |
Backups
Section titled “Backups”| Type | Fires when |
|---|---|
backup.success | A backup completes |
backup.failed | One does not |
Kiosk and security
Section titled “Kiosk and security”| Type | Fires when |
|---|---|
kiosk.request | An assistance request is raised at the kiosk |
kiosk.resolved | It is approved or denied |
security.resolved | A security approval request is decided |
Identity
Section titled “Identity”| Type | Fires when |
|---|---|
identity.action | An identity action, such as an MFA reset or a sign-out, is taken on an account. Sent only to people with identity.view |
Where to receive them
Section titled “Where to receive them”In the console. Automatic. This is what makes the desk update itself.
In your own system. Register an outbound webhook. Signed with HMAC-SHA256, and you can filter to specific types.
In a browser client of your own. Subscribe to /api/events with
EventSource, inside an authenticated session.
ticket.comment fires for internal notes too, but not to everybody. A note
generates an event carrying the ticket.internal permission, so only people who
could read the note are told one was added. It still never sends an email. The
note’s text is never in the event either way.
sla.breach fires once per item. A breach that stays breached does not
generate a new event every minute.
Order is not guaranteed. Two events fired close together can arrive in either order at a webhook receiver. Build for that.
Who receives them
Section titled “Who receives them”Three filters are applied in order, and all three must pass.
Tenant. A subscriber receives only their own tenant’s events.
Permission. Every event names the permission that governs the record behind
it: a repair event carries repair.view, a kiosk event client.view, a local
administrator password retrieval device.laps.read. Somebody who could not open
the record is not told about it. A role holding * passes this check for
everything. The permission keys are listed in
permissions.
Site. Where the event belongs to a site, only people whose access covers that site receive it. Somebody with no site restriction receives all of them.
Some events belong to no single site: a backup result, a monitor alert, a fleet-wide sync, a bulk loan checkout. Those are treated as unassigned, so people restricted to a site do not receive them. The alternative would be telling every campus about every other campus.
Webhooks are not filtered this way
Section titled “Webhooks are not filtered this way”An outbound webhook endpoint is configured per school by an administrator, not per person, so there is nobody to check a permission against. Endpoints receive every event for their tenant, filtered only by the types you selected when you registered them.