POST-Request mit strukturierten JSON-Daten an deine hinterlegte URL.
Die Einrichtung, die Zustellung und die Signaturprüfung sind für alle Webhooks gleich. Wie du Webhooks anlegst und absicherst, liest du unter Webhooks einrichten. Auf dieser Seite findest du nur, was für Angebote gilt: die verfügbaren Events und ihre Payloads.
Der Envelope
Jeder Angebots-Webhook hat denselben Aufbau. Das eigentliche Objekt steckt unterdata, daneben liegen Metadaten zum Ereignis und der Vertriebskanal als Kontext.
Der Vertriebskanal, in dessen Kontext das Ereignis entstand.
null, wenn sich kein Kanal auflösen ließ.Die Nutzdaten des Ereignisses. Der Schlüssel darin benennt das betroffene Objekt, bei Angebots-Events also
offer.HTTP-Header
Jede Zustellung bringt diese Header mit:Verfügbare Events
Aktuell ist
offer.expired das einzige Angebots-Event mit Webhook. Diese Liste wächst, wenn weitere Ereignisse hinzukommen.offer.expired
Das Ereignis feuert, sobald die Gültigkeit eines Angebots verstreicht, solange es noch offen ist. Ein bereits angenommenes oder archiviertes Angebot läuft nie ab.
Fynn erkennt den Ablauf auf zwei Wegen: über eine regelmäßige Prüfung im Hintergrund und beim ersten Aufruf des abgelaufenen Links durch einen Empfänger. Egal welcher Weg zuerst greift, das Ereignis wird je Ablauf genau einmal gesendet. Verlängerst du ein abgelaufenes Angebot und es läuft erneut ab, gilt das als neues Ereignis.
Das offer-Objekt
Unter data.offer erhältst du das Angebot in seiner Lese-Darstellung. Die wichtigsten Felder:
Eindeutige Kennung des Angebots. Nutze sie, um über die Angebote-API den vollständigen Stand inklusive Kunde, Abonnement und Empfänger zu laden.
Der zuletzt gespeicherte Status:
open, signing, awaiting_invoice_details, signed oder archived. Ein abgelaufenes Angebot behält seinen Status (meist open), der Ablauf selbst ergibt sich aus validUntil.Datum, bis zu dem das Angebot angenommen werden konnte (ISO 8601). Bei
offer.expired liegt dieser Zeitpunkt in der Vergangenheit.Die Dokument-Blöcke des Angebots (Briefkopf, Parteien, Abonnement, Texte und mehr). Den Aufbau der Blöcke findest du unter Kernkonzepte.
Die Payload ist bewusst schlank. Verschachtelte Objekte wie
customer, subscription, recipients und die Dokument-Referenzen sind im Webhook nicht ausgefüllt und kommen als leeres Objekt, leere Liste oder null. Brauchst du diese Details, lade das Angebot mit der id aus der Payload über GET /offers/{id} nach.