Webhooks
Webhooks actively notify you about events like status changes, delivery or a low balance, instead of you having to poll.
Preview, not live yet
This page shows the planned event registry and signature contract from Epic 19. Header format and the replay window can still change before the Epic 19 release. Do not wire a production receiver against these exact bytes yet.
| Event | Fires when |
|---|---|
order.status_changed | A partner order changes status (e.g. printed, sent). |
order.delivered | A letter has been delivered. |
order.awaiting_fix | A send has failed and is waiting for you to fix it. |
order.failed | A send has failed permanently. |
approval.pending | A letter is waiting in the approval queue for your decision. |
approval.decided | An approval has been decided (accepted, rejected, via cooldown or timeout). |
wallet.low | Your available wallet balance drops below your configured threshold (once per downward crossing). |
wallet.topup_succeeded | A wallet top-up has been credited. |
Signature (provisional)
Every delivery carries an HMAC-signed header so you can verify authenticity before processing the payload.
X-FrankKi-Signature: t=<unix-seconds>,v1=<hex> v1 = HMAC-SHA256(secret, t + "." + rawBody)
Replay window: 300s. Extra headers: X-FrankKi-Event-Id, X-FrankKi-Event-Type.
Delivery attempts and backoff (provisional)
Failed deliveries are retried with growing delays, up to a fixed maximum number of attempts.
1m, 5m, 30m, 2h, 6h, 24h
Maximum 7 attempts total, then the delivery is marked exhausted.
Sandbox note
A send made with a test token (the sandbox from this developer portal) fires the same webhooks as a live send, with the payload's mode field set to "test". This lets you verify your webhook receiver end to end, signature check included, without money or paper.
Check the mode field before you act on an event. Test events are a rehearsal, not a real send.
Trust and live status
Machine-readable service facts and the current operational status of the partner interface are publicly available at all times, no login needed.