Webhooks
Webhooks benachrichtigen dich aktiv über Ereignisse wie Statuswechsel, Zustellung oder ein niedriges Guthaben, statt dass du selbst pollst.
Vorschau, noch nicht live
Diese Seite zeigt die geplante Event-Registry und den geplanten Signatur-Vertrag aus Epic 19. Header-Format und Replay-Fenster können sich bis zum Epic-19-Release noch ändern. Verdrahte noch keinen produktiven Empfänger gegen diese genauen Bytes.
| Event | Wann es feuert |
|---|---|
order.status_changed | Der Status eines Partner-Auftrags wechselt (z. B. gedruckt, versendet). |
order.delivered | Ein Brief wurde zugestellt. |
order.awaiting_fix | Ein Versand ist fehlgeschlagen und wartet auf eine Korrektur durch dich. |
order.failed | Ein Versand ist endgültig fehlgeschlagen. |
approval.pending | Ein Brief wartet in der Freigabe-Queue auf deine Entscheidung. |
approval.decided | Eine Freigabe wurde entschieden (angenommen, abgelehnt, per Cooldown oder Timeout). |
wallet.low | Dein verfügbares Guthaben unterschreitet deinen eingestellten Schwellenwert (einmal pro Abwärtsbewegung). |
wallet.topup_succeeded | Eine Guthaben-Aufladung wurde gutgeschrieben. |
Signatur (vorläufig)
Jede Zustellung trägt einen HMAC-signierten Header, mit dem du die Echtheit prüfst, bevor du den Payload verarbeitest.
X-FrankKi-Signature: t=<unix-seconds>,v1=<hex> v1 = HMAC-SHA256(secret, t + "." + rawBody)
Replay-Fenster: 300s. Zusätzliche Header: X-FrankKi-Event-Id, X-FrankKi-Event-Type.
Zustell-Versuche und Backoff (vorläufig)
Fehlgeschlagene Zustellungen werden mit steigenden Wartezeiten wiederholt, bis zu einer festen Obergrenze an Versuchen.
1m, 5m, 30m, 2h, 6h, 24h
Maximal 7 Versuche insgesamt, danach gilt die Zustellung als ausgeschöpft.
Sandbox-Hinweis
Ein Versand mit einem Test-Token (der Sandbox aus diesem Entwickler-Portal) feuert dieselben Webhooks wie ein Live-Versand, mit dem Feld mode auf "test" gesetzt im Payload. So kannst du deinen Webhook-Empfänger Ende-zu-Ende prüfen, inklusive Signaturprüfung, ohne Geld oder Papier.
Prüfe das Feld mode, bevor du auf ein Event reagierst. Test-Events sind eine Probe, kein echter Versand.
Vertrauen und Live-Status
Maschinenlesbare Servicefakten und der aktuelle Betriebsstatus der Partner-Schnittstelle stehen jederzeit offen zur Verfügung, ohne Login.