Webhooks and API keys
A job moves through several states, and there are two ways to find out about it: poll GET /jobs/{id}/events, or subscribe and have the transitions pushed to you. Polling is fine while you are building. Webhooks are what you want in production, because a job can sit queued until the device comes back online or the job expires, and there is nothing useful to poll in the meantime.
Delivery is at-least-once and every payload is signed, so a receiver has two jobs beyond reading the event: verify the signature, and dedupe on the event id. Both are covered below.
API keys are on this page because they are the other thing you manage rather than simply use. Keys are how your own server authenticates. Enrollment tokens, on the devices page, are how a customer's machine does.
Webhooks
| Method | Path | Notes |
|---|---|---|
| POST | /webhooks | { "url": "...", "events": ["job.*", "printer.state_changed"], "description": "..." } → returns the endpoint including its secret (shown once) |
| GET | /webhooks and /webhooks/{id} | |
| PATCH | /webhooks/{id} | url, events, disabled |
| DELETE | /webhooks/{id} | |
| POST | /webhooks/{id}/test | Sends a synthetic ping event so you can verify your receiver |
Event types, subscribable with wildcards:
job.created,job.queued,job.sent,job.printing,job.succeeded,job.failed,job.canceled,job.expiredprinter.state_changed,printer.discovered,printer.removeddevice.state_changed,device.enrolled,device.revoked
Delivery payload:
{
"id": "evt_3mm2z",
"type": "job.succeeded",
"created_at": "...",
"data": { ...full job object... }
}
- Every delivery is signed:
PrintSocket-Signature: t=<unix>,v1=<hmac-sha256>computed overt.payload. Verify it, and reject timestamps outside a 5-minute tolerance. Secrets are per endpoint and rotatable. - Failed deliveries retry with exponential backoff for 24 h. An endpoint that keeps failing is disabled automatically, with a
webhook.disablednotification event. - Delivery is at-least-once, so dedupe on the
evt_id.
API keys
Requires the manage scope.
| Method | Path | Notes |
|---|---|---|
| GET | /api_keys | Secrets are never re-shown; returns the prefix and last 4 characters |
| POST | /api_keys | { "name": "...", "scopes": ["print"], "mode": "live" } → secret shown once |
| DELETE | /api_keys/{id} | Immediate revocation |
Account and billing management lives in the dashboard rather than this API.