Let your integration create and look after its own webhook endpoints.
Nobody enjoys pasting URLs into a portal. With the Manage webhooks
permission (webhooks:manage), your integration can add and maintain its own
webhook endpoints. It's part of Full access and not part of
Download only.
A key sees and manages only the endpoints it created. Any other endpoint
answers 404 WEBHOOK_NOT_FOUND, whether a lab manager added it in the portal,
another key created it, or it belongs to another lab.
Lab owners and managers still see and manage every endpoint in the portal, where key-created ones show "Created by API key" with the key's label.
Revoking a key also disables every endpoint it created and cancels their pending deliveries, so a leaked key can't keep receiving events after you revoke it. An owner or manager can re-enable such an endpoint in the portal on purpose.
label: 1 to 60 characters.url: a public https:// address on port 443, at most 2048 characters,
with no credentials or fragment. Every DNS answer must be a public address.
The same check runs on every URL change and before every delivery.eventTypes: a list of event types, or ["*"] for every current and
future event. A key can subscribe only to events it may read itself:
export.* events need exports:read, and ["*"] needs every read
permission the current events require. Endpoints a key created receive only
events that key can read, so a future event type that needs a permission the
key lacks isn't sent there. An empty list [] receives only test pings.https://Hooks.Example.com:443/in equals https://hooks.example.com/in.
The answer is 409 WEBHOOK_URL_EXISTS, and when your key created the
existing endpoint, data.webhookId names it.whsec_...) is only in the
create and rotate responses. Store it right away.A create timed out? No problem.
The URL rule doubles as your retry safety net, so creating an endpoint needs
no Idempotency-Key. Just send the create again. A 409 with
data.webhookId tells you the first attempt worked. Its secret was only in
the response you lost, so call POST /webhooks/{webhookId}/secret for a new
one before you receive events. For the next 24 hours the unseen previous
secret also still signs.
If secret storage is down. Creating, rotating and changing the label, URL
or events answer 503 SERVICE_UNAVAILABLE and change nothing; retry later.
Enabling, disabling and deleting still work. A test is accepted too, but its
ping waits until secret storage is back.
GET /api/print-lab/v1/webhooks
Authorization: Bearer spreadu_lab_...{
"items": [
{
"id": "cm3wh0000000000000000001",
"label": "Order sync",
"url": "https://hooks.example.com/spreadu",
"eventTypes": ["*"],
"enabled": true,
"createdAt": "2026-11-03T09:00:00.000Z",
"updatedAt": "2026-11-03T09:00:00.000Z",
"lastDelivery": {
"status": "SUCCEEDED",
"attemptCount": 1,
"lastStatusCode": 204,
"lastErrorCode": null,
"lastAttemptAt": "2026-11-03T09:01:12.000Z"
},
"deadDeliveries": { "count": 0, "latestAt": null }
}
]
}lastDelivery is the endpoint's most recent delivery, test pings included, or
null before the first one.
status is PENDING, SUCCEEDED, DEAD (all retries failed) or
CANCELLED (the endpoint was disabled).lastErrorCode is TIMEOUT, DNS_REJECTED, CONNECT_FAILED, TLS_FAILED,
REDIRECT, HTTP_STATUS or null.Because it shows only the newest delivery, lastDelivery can read SUCCEEDED
while older ones are dead. deadDeliveries counts those; see
when a delivery gives up.
POST /api/print-lab/v1/webhooks
Content-Type: application/json
{ "label": "Order sync", "url": "https://hooks.example.com/spreadu", "eventTypes": ["*"] }201 Created returns the endpoint plus "secret": "whsec_...". New endpoints
start enabled.
Send only the fields you want to change: label, url, eventTypes or
enabled.
PATCH /api/print-lab/v1/webhooks/cm3wh0000000000000000001
Content-Type: application/json
{ "enabled": false }The response is the updated endpoint, without a secret. Disabling cancels
deliveries that are still pending, and enabling again doesn't bring them back.
Use GET /events to catch up.
POST /api/print-lab/v1/webhooks/cm3wh0000000000000000001/secretReturns the endpoint plus the new secret. For the next 24 hours both secrets
sign every delivery (webhook-signature: v1,<new> v1,<old>), so you can switch
your receiver without missing an event.
POST /api/print-lab/v1/webhooks/cm3wh0000000000000000001/test{ "eventId": "ping_cm3dl0000000000000000001" }Your receiver gets a signed ping whose webhook-id header and body id
equal eventId. A ping is never part of /events and never moves your cursor.
The result shows up in lastDelivery.
DELETE /api/print-lab/v1/webhooks/cm3wh0000000000000000001{ "id": "cm3wh0000000000000000001", "deleted": true }This also deletes the endpoint's delivery history. Deleting it again answers
404 WEBHOOK_NOT_FOUND.
| Code | Status | What to do |
|---|---|---|
BAD_REQUEST | 400 | Use a public HTTPS URL and events your key can read. When present, data.field names the refused field, url or eventTypes. It's a hint for people, not declared in the contract, so don't branch on it. |
INSUFFICIENT_SCOPE | 403 | Create a key with Manage webhooks. |
WEBHOOK_NOT_FOUND | 404 | Use an ID your key created (see GET /webhooks). |
WEBHOOK_URL_EXISTS | 409 | If data.webhookId is present, update that endpoint. Otherwise ask a lab owner or manager to manage the existing endpoint in the portal. |
ENDPOINT_LIMIT_REACHED | 409 | Delete an endpoint, or ask a lab manager to remove one. |
WEBHOOK_DISABLED | 409 | Enable the endpoint before sending a test. |
SANDBOX_BUSY | 409 | Test mode only, when rotating: another test-mode write is running. Retry shortly. |
SERVICE_UNAVAILABLE | 503 | Secret storage is unavailable. Nothing changed; retry later. |
Like every call, these can also answer 401 INVALID_API_KEY or
403 API_ACCESS_DISABLED when the key is revoked or access is switched off.
All error codes live in one
place.
Allow analytics to help us improve these docs? We measure page visits and outgoing links. No session recordings. Privacy policy