Webhooks

Create a webhook endpoint

POST/v2/accounts/{accountId}/webhooksTry it

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
  • accountIdstringrequired
    Unique identifier of the account, or the alias @me for 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 403 ACCOUNT_ACCESS_DENIED.
Body application/json
  • urlstring (uri)required
  • eventsarray of stringrequired
  • descriptionstring, nullable

Responses

200The endpoint, and its signing secret
  • successboolean
  • secretstring
    The HMAC key of X-Printags-Signature, given only here
  • webhookWebhook
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

Request
curl -X POST "https://api.printags.com/v2/accounts/@me/webhooks" \
  -H "Authorization: Bearer $PRINTAGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://boutique.example/wp-json/printags/v1/webhook","events":["order.updated","order.shipped"],"description":"WooCommerce"}'
Response 200
{
  "success": true,
  "secret": "whsec_0f3c...",
  "webhook": {
    "id": "3c0e8f8a-0000-4000-8000-000000000001",
    "endpoint": "https://boutique.example/wp-json/printags/v1/webhook",
    "description": "WooCommerce",
    "webhook_events": [
      {
        "name": "order.shipped"
      }
    ]
  }
}