API Endpoint Reference / Webhooks
Create a webhook endpoint
POST https://api.printhiv3d.com/v1/webhooks
Operation ID createWebhook. Requires the webhooks:write API key scope.
Subscribes an HTTPS receiver to event_types. The response carries signing_secret once; store it, because later reads never return it. An organization may hold 20 endpoints.
Request body
Content type application/json.
| Field | Type | Required | Description |
|---|
name | string | Yes | |
url | uri | Yes | An HTTPS URL with a public DNS hostname. IP literals, credentials and fragments are refused. |
event_types | ("model.created" | "model_file.uploaded" | "job.created" | "job.assigned" | "job.started" | "job.paused" | "job.resumed" | "job.recovered" | "job.completed" | "job.failed" | "job.cancelled" | "printer.ready" | "printer.online" | "printer.offline")[] | Yes | |
enabled | boolean | No | |
Responses
| Status | Description |
|---|
201 | Default Response |
400 | Default Response |
401 | Default Response |
403 | Default Response |
409 | Default Response |
503 | Default Response |
201 response fields
| Field | Type | Required | Description |
|---|
id | uuid | Yes | |
organization_id | uuid | Yes | |
name | string | Yes | |
url | string | Yes | |
event_types | string[] | Yes | The types the endpoint subscribes to. Print Hive adds types, so a reader ignores a name it does not know. |
enabled | boolean | Yes | |
consecutive_failures | integer | Yes | |
created_at | string | Yes | |
updated_at | string | Yes | |
signing_secret | string | Yes | The HMAC-SHA256 secret that signs every delivery. Returned only when the endpoint is created and when rotate_secret is true. Store it now; later reads never return it. |
400 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
requestId | string | No | |
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 | |
409 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
requestId | string | No | |
503 response fields
| Field | Type | Required | Description |
|---|
error | string | No | |
message | string | No | |
requestId | string | No | |
Example 201 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",
"signing_secret": "4f1b9c7d2e6a8035b1d4f7e9a2c5d8b0e3f6a9c1d4b7e0f2a5c8d1b4e7f0a3c6"
}