Webhook & API reference

Start with Webhooks & content push to configure the manifest and establish a connection. This reference describes the host's content API and the status callbacks your backend receives.

Endpoint reference

All paths below are relative to https://api.paperlesspaper.de/v1/integration-papers. JSON requests use Content-Type: application/json. Responses use Cache-Control: no-store.

Connection endpoints use the token returned by grant exchange. They do not use the general x-api-key upload flow or the callback token.

The current limits are 30 content submissions per minute per connection and 60 grant exchanges per minute per client IP. A rate-limited request returns 429; respect Retry-After before retrying.

Status webhook

The host posts to the callback URL derived from the saved manifest:

POST /api/paper-status HTTP/1.1
Authorization: Bearer <callbackToken>
Content-Type: application/json

Example frame event:

{
  "eventId": "<stable-event-id>",
  "connectionId": "<connection-id>",
  "paperId": "<paper-id>",
  "requestId": "<host-request-id>",
  "messageId": "order-482-ready",
  "state": "synced",
  "deviceId": "<frame-id>",
  "frameName": "Kitchen",
  "occurredAt": "2026-09-20T10:00:00.000Z"
}

Receiver requirements

1. Look up the active stored connection by connectionId and check paperId matches.
2. Validate Authorization: Bearer <callbackToken> using that connection's callback token. Use a constant-time secret comparison. Reject unauthenticated or mismatched events.
3. Validate the payload and durably store or enqueue the event, with a unique constraint on eventId.
4. Return a 2xx response promptly after durable acceptance. A duplicate already stored successfully should also receive 2xx.
5. Process notifications asynchronously. Correlate by request and frame, and tolerate events arriving out of order; a delayed prepared event must not downgrade an already synced delivery.

There is no HMAC signature in this protocol. The separate callback bearer token authenticates the request. Response bodies are ignored, and the host times out callback requests after 15 seconds.

Retries and retention

Network failures, timeouts, and non-2xx responses trigger retries with exponential backoff, capped at one hour between attempts. Actual delivery also depends on the callback queue's sweep. Redirects are not followed. Events are retained for seven days; failed callbacks do not block later events.

Expect possible duplicate callbacks and uploads after a crash. Exactly-once delivery is not guaranteed. Keep event deduplication records for at least the callback retry window. Callbacks stop when the connection is revoked or its access/configuration is no longer valid.

Before every attempt, the host resolves the callback hostname, rejects private/reserved addresses, and pins the validated address for the connection. The endpoint must use public HTTPS on port 443 in production.

Callback states

Paper-level events omit deviceId and frameName. A frame event applies only to the named frame, not to every frame displaying the paper.

synced requires the device's pictureSynced flag, a newer file version, matching upload timing, fresh reachability, and the latest relevant upload log tied to the same content revision. It reports device synchronization, not optical verification of the panel. Missing or stale evidence cannot produce success.

A frame that already reached a terminal state such as synced keeps that historical result when a later message arrives. Do not interpret a paper-level superseded event as evidence that an earlier frame synchronization never happened.

Poll the latest status

Use polling to reconcile your UI or recover when a callback could not be processed:

curl --fail-with-body \
  "https://api.paperlesspaper.de/v1/integration-papers/connections/<connection-id>/status" \
  -H "Authorization: Bearer <content-api-bearer-token>"

Example response (delivery records may contain additional database fields):

{
  "paperId": "<paper-id>",
  "name": "Kitchen messages",
  "state": "active",
  "messageId": "order-482-ready",
  "deliveries": [
    {
      "deviceId": "<frame-id>",
      "frameName": "Kitchen",
      "state": "synced"
    }
  ]
}

The top-level state describes the latest request for this connection's current generation. It is separate from callback and frame states:

Deliveries can be pending before an upload, followed by the frame states in the callback table. A request can remain active even when all existing deliveries are synced, because additional frames can be assigned during the observation window.

This endpoint is not a history API and accepts no request ID selector. Request and delivery records expire after 30 days. The current paper content persists independently, so an empty status does not necessarily mean the paper has no content.

Errors and troubleshooting

After a rendering failure, the failed message remains the paper's current source until replaced. Neither revocation nor request-record expiry is a content deletion operation.