Events and webhooks
Receive signed changes, reconcile their state and recover deliveries.
Subscribe to events
Create an HTTPS webhook endpoint with events matching the types your integration handles. Use webhooks:write and an idempotency key. Save the returned signing_secret in your secret manager; it is shown at creation and rotation. The endpoint URL is validated against unsafe destinations.
A webhook receives an event envelope with id, type, api_version, environment, created_at and data. Filter the environment and deduplicate the event ID. Do not assume arrival order. Fetch the current resource when acting on a state change.
Verify the raw body
Read the x-paperboy-signature header. Its t value is the Unix timestamp in seconds and each v1 value is a base64url HMAC-SHA256. The signed message is the timestamp, a period, then the exact raw request body. Verify against your secret with a constant-time comparison before parsing or processing the payload.
Check timestamp freshness using your receiving policy and reject replayed event IDs. Secret rotation temporarily signs with both current and previous secrets. Accept either valid v1 signature during your rotation, then retire the previous secret.
Acknowledge and recover
Return a successful HTTP status promptly after durably accepting an event, then process it asynchronously. Delivery is retried on failure and can reach dead_letter after the retry budget. Use /v1/webhook-deliveries for outcomes and its replay endpoint to request another attempt.
Sandbox order progression uses the same event and outbox owners as the API. Configuring a webhook creates an outbound delivery to that endpoint; use an endpoint you control. Sandbox printing remains simulated.