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.

FieldTypeRequiredDescription
namestringYes
urluriYesAn 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
enabledbooleanNo

Responses

StatusDescription
201Default Response
400Default Response
401Default Response
403Default Response
409Default Response
503Default Response

201 response fields

FieldTypeRequiredDescription
iduuidYes
organization_iduuidYes
namestringYes
urlstringYes
event_typesstring[]YesThe types the endpoint subscribes to. Print Hive adds types, so a reader ignores a name it does not know.
enabledbooleanYes
consecutive_failuresintegerYes
created_atstringYes
updated_atstringYes
signing_secretstringYesThe 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

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo

401 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo

403 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo

409 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo

503 response fields

FieldTypeRequiredDescription
errorstringNo
messagestringNo
requestIdstringNo

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"
}