API Endpoint Reference / Webhooks
List webhook endpoints
GET https://api.printhiv3d.com/ v1/ webhooksOperation ID listWebhooks. Requires the read API key scope.
Subscribe an HTTPS receiver to library, print job, and printer events with REST or MCP. API keys need webhooks:write to create, update, rotate, delete, or test an endpoint. Reads need read access. Organization comes from the authenticated principal.
## Configuration
REST paths are relative to /v1:
- GET /webhooks lists endpoint metadata without secrets. - GET /webhooks/{id} reads one endpoint. - GET /webhooks/{id}/attempts reads the latest 100 delivery attempts and their events. - POST /webhooks accepts name, url, event_types, and enabled. - PATCH /webhooks/{id} updates those fields; rotate_secret:true replaces the secret. - DELETE /webhooks/{id} removes the endpoint. - POST /webhooks/{id}/test records a targeted synthetic event and returns immediately.
MCP exposes webhooks_list, webhooks_create, webhooks_update, webhooks_delete, and webhooks_test. Mutations require confirm:true. Each organization may have 20 endpoints. An endpoint subscribes to one or more of the event types below. Creation and rotation return signing_secret exactly once. Save it in the receiver's secret store. Subsequent reads never return it. The API and worker need the same WEBHOOK_ENCRYPTION_KEY, a base64-encoded 32-byte key. Secrets use AES-256-GCM encryption at rest. Keep that key stable across restarts. Rotating an endpoint invalidates its previous secret for subsequent attempts.
## Event types
- model.created and model_file.uploaded: library events. - job.created, job.assigned, job.started, job.paused, job.resumed, job.recovered, job.completed, job.failed, and job.cancelled: the life of a Print Job. - printer.ready, printer.online, and printer.offline: the state of a Printer.
A type name is permanent. Hive adds types and fields, and never renames or removes one, so ignore a type or a data field that you do not know.
## Event bodies
Every POST has this JSON envelope. Receivers must tolerate additional data fields:
```json { "id": "00000000-0000-4000-8000-000000000001", "type": "model.created", "occurred_at": "2026-10-15T12:00:00.000Z", "org_id": "00000000-0000-4000-8000-000000000002", "data": { "model_id": "00000000-0000-4000-8000-000000000003", "name": "Example model" } } ```
model.created records a newly created Model, including Models created in the web app and through Harvest. Duplicate saves of the same Model do not create a new event.
model_file.uploaded uses the same envelope with type model_file.uploaded and:
```json { "model_file_id": "00000000-0000-4000-8000-000000000004", "model_id": "00000000-0000-4000-8000-000000000003", "filename": "example.3mf", "size": 12345, "download_path": "/v1/files/00000000-0000-4000-8000-000000000004/download-url" } ```
webhook.test uses the same envelope with type webhook.test and data {"test":true}. It is a synthetic event targeted only at the endpoint selected for a test. Tests are limited to one per endpoint every 60 seconds (HTTP 429).
### Print job and printer events
For these types, id is the id of the Farm Event that records the fact, and data is that event's payload, so it matches the payload of the item that the live event stream yields for the same event. Print Job ids are strings, and Printer ids are UUIDs. A job.completed event looks like this:
```json { "id": "00000000-0000-4000-8000-000000000005", "type": "job.completed", "occurred_at": "2026-11-18T10:00:00.000Z", "org_id": "00000000-0000-4000-8000-000000000002", "data": { "jobId": "4821", "printerId": "00000000-0000-4000-8000-000000000006", "jobName": "phone-stand.3mf", "status": "COMPLETED", "previousStatus": "IN_PROGRESS", "printCompletedAt": "2026-11-18T10:00:00.000Z", "claimGeneration": "00000000-0000-4000-8000-000000000007" } } ```
The data fields of each type:
- job.created: jobId, printerId (null until a printer is chosen), jobName, modelFileId, batchId, and source (how the job was created). - job.assigned: jobId, printerId, jobName, modelFileId, batchId, and claimGeneration, the id of this run of the job. - job.started: jobId, printerId, jobName, status (IN_PROGRESS), previousStatus (null for a print that did not come through the queue), and claimGeneration. - job.paused: jobId, printerId, jobName, status (PAUSED), previousStatus, errorCode, and errorMessage (null when the pause has no printer error). - job.resumed: jobId, printerId, jobName, status (IN_PROGRESS), and previousStatus (PAUSED). - job.recovered: jobId, printerId, jobName, status (IN_PROGRESS), and previousStatus (FAILED, ERROR, or RETRYING). The printer reported the print again after Print Hive marked it ended, so this undoes the earlier job.failed. - job.completed: jobId, printerId, jobName, status (COMPLETED), previousStatus, printCompletedAt, and claimGeneration. - job.failed: the job.completed fields with status FAILED, and errorCode and errorMessage (each null when the printer reported none). - job.cancelled: the job.completed fields with status CANCELLED. printerId is null for a queued job that no printer claimed. - printer.ready: printerId, releasedJobId (the completed job whose lock this released, or null), readySource, and readyUpdatedSource. The printer is marked ready and holds no completed-job lock. - printer.online: printerId, printerName, and observedAt. - printer.offline: printerId, printerName, observedAt, and lastSeenAt, the last time the printer was seen connected (or null).
printer.online and printer.offline fire once for each change of the printer's connection, and never while it stays in one state. A printer that was never connected is not offline. printer.offline comes from the printer's Host reporting it, and also from a Host that stops answering: Print Hive then marks the Host's printers offline when its 90-second lease expires, and a sweep that runs every 30 seconds finds the expired lease, so that offline event can arrive up to about two minutes after the Host stopped. observedAt is when Print Hive recorded the change.
An event is stored only when an endpoint of the organization subscribes to its type at that moment. Subscribing later does not send earlier events. After an outage, read what you missed with GET /v1/organizations/{orgId}/events, which needs the events:read scope: its items carry the same ids, so you can match them with the deliveries that you did receive. Pass kinds=printer.online,printer.offline to read the printer connection events, which that endpoint returns only when you name them.
The file event means .3mf bytes have been registered, not that processing or slicing has completed. Use the authenticated download reference with your own organization-scoped credential. No credential or long-lived signed URL travels in an event. Delivery order is not guaranteed. A file event can arrive before its Model event. Receivers must deduplicate using id before starting work.
## Delivery and signature
The API transaction writes only an outbox event. A BullMQ worker fans out committed events and performs HTTPS delivery. Redis downtime does not discard committed events. Responses never wait for a receiver. Only public HTTPS destinations with DNS hostnames are allowed; IP literal URLs are refused. Hostnames must resolve through the worker's configured DNS servers. Hosts-file and NSS overrides are not consulted. The worker validates every returned A and AAAA address before connecting; any private or special-use answer rejects the whole destination. Connections may try multiple validated addresses, including IPv6 when IPv4 is unavailable, within one 15-second DNS and HTTPS deadline. The worker pins that validated answer set and does not follow redirects. A connection that fails or stalls before TLS completes may fall back to another validated address within that deadline. After TLS completes, a failed send or HTTP response ends this attempt; the durable delivery retry handles failures.
Headers:
- Content-Type: application/json - X-Hive-Event-Id: the envelope id, stable across retries and endpoints - X-Hive-Signature: t=<unix-seconds>,v1=<hex-digest>
The digest is HMAC-SHA256(secret, timestamp + "." + rawRequestBody). Verify the original bytes before JSON parsing. Check timestamp freshness and use a constant-time comparison. Each attempt gets a fresh timestamp and signature. The @printhive/api package does all of this in verifyWebhookSignature({ rawBody, signatureHeader, secret, toleranceSeconds }), which resolves to true only for a fresh, authentic delivery. Without it, this TypeScript/Node example verifies the signature:
```typescript import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyHiveWebhook( rawBody: Buffer, signature: string, secret: string, nowSeconds = Math.floor(Date.now() / 1000) ): boolean { const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(signature); if (!match) return false; const timestamp = Number(match[1]); if (!Number.isSafeInteger(timestamp) || Math.abs(nowSeconds - timestamp) > 300) { return false; } const expected = createHmac("sha256", secret) .update(timestamp + ".").update(rawBody).digest(); return timingSafeEqual(expected, Buffer.from(match[2], "hex")); } ```
Return a 2xx response after durably accepting the event. Delivery is at least once, so a worker crash after your response can cause a duplicate. Non-2xx and transport failures retry with exponential backoff for at most 24 hours before dead-letter. Delivery attempts persist endpoint, event id, attempt number, status code, latency, a redacted error, and next retry. At most five deliveries per endpoint run concurrently across workers. Ten consecutive failed delivery attempts disable an endpoint and create an organization notification. Disabled endpoints pause queued deliveries; re-enabling resumes them within the 24-hour window. Local encryption configuration failures do not penalize the endpoint. Dispatched events and their terminal delivery history are retained for 30 days. Correct the URL and explicitly re-enable the endpoint after investigating.
Responses
| Status | Description |
|---|---|
200 | Default Response |
401 | Default Response |
403 | Default Response |
500 | Default Response |
401 response fields
| Field | Type | Required | Description |
|---|---|---|---|
error | string | No | |
message | string | No | |
requestId | string | No |
403 response fields
| Field | Type | Required | Description |
|---|---|---|---|
error | string | No | |
message | string | No | |
requestId | string | No |
500 response fields
| Field | Type | Required | Description |
|---|---|---|---|
error | string | No | |
message | string | No | |
requestId | string | No |
Example 200 response
[
{
"id": "2a6f0d8e-5c3b-4d19-b7a4-9e1c8f5d3a60",
"organization_id": "3b9e4d71-0c2f-4a58-8e6d-91f2a7c4b605",
"name": "Fulfilment service",
"url": "https://hooks.example.com/printhive",
"event_types": [
"job.started",
"job.completed",
"job.failed",
"printer.offline"
],
"enabled": true,
"consecutive_failures": 0,
"created_at": "2026-11-04T18:00:00.000Z",
"updated_at": "2026-11-04T18:00:00.000Z"
}
]