Webhooks
Create a webhook endpoint
Subscribes a URL to events. The answer holds the signing secret, given this once only: store it. The URL must be public (http or https, 255 characters at most); at most 25 endpoints per account. An endpoint created with an OAuth token is removed when that authorization is revoked. Events, delivered as a JSON POST to the endpoint: order.created (an order is created, a firm order once processed), order.updated (every status change of an order: data.status is the new status, e.g. in_queue, manufacturing, shipped, delivered, cancelled) and order.shipped (the order left: data.shippings[].trackingNumber carries the tracking number; sent again when a new label gives a new number). order.encoded is accepted in events but not sent today. The body: { id, created, event, livemode, data }, id the event's id (the same for every endpoint and every retry: deduplicate on it), created its epoch seconds, data the order as getOrder returns it in version 1. Headers: X-Printags-Event (the event), X-Printags-Delivery (the delivery's id) and X-Printags-Signature: t=<epoch seconds>,v1=<hex>, where v1 is the HMAC-SHA256, keyed by the endpoint's secret (whsec_...), of <t>.<raw body>: recompute it on the raw bytes, compare in constant time and refuse a t more than 5 minutes old. Answer 2xx within 10 seconds; anything else is retried with a backoff, up to 15 attempts. An endpoint created with a test credential (a sk_test_ key, a test OAuth token) receives test orders' events only (livemode false); any other endpoint receives the events of both, told apart by livemode.
Request
Authorization
Bearer token
Send your API key in the Authorization header: Authorization: Bearer sk_test_…. A sk_test_ key creates and sees test orders only. Keys and test mode.
Path parameters
accountIdstringrequiredUnique identifier of the account, or the alias@mefor the account authenticated by the token. An API key or an OAuth token acts on its own account only: another account's id is refused with 403ACCOUNT_ACCESS_DENIED.
Body application/json
urlstring (uri)requiredeventsarray of stringrequireddescriptionstring, nullable
Responses
200The endpoint, and its signing secret
successbooleansecretstringThe HMAC key ofX-Printags-Signature, given only herewebhookWebhook
400url or events missing (MISSING_PARAMETERS), a URL that is not public (INVALID_WEBHOOK_URL), a bad list (INVALID_PARAMETERS), or an event name that does not exist (UNKNOWN_WEBHOOK_EVENTS, with unknown_events)
Type: Error
401Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (INVALID_TOKEN)
Type: Error
403The API key is inactive or revoked (INACTIVE_API_KEY), or the path names another account (ACCOUNT_ACCESS_DENIED); with an OAuth access token: a token of scope mcp (INSUFFICIENT_SCOPE), a path naming another account or a person no longer a member of it (ACCOUNT_ACCESS_DENIED), a real token on the sandbox host (SANDBOX_REQUIRES_TEST_KEY)
Type: Error
409The account already holds 25 endpoints (WEBHOOK_LIMIT_REACHED)
Type: Error
500Internal server error
Type: Error