Webhooks

Webhooks für Angebote benachrichtigen dein System automatisch über Ereignisse im Lebenszyklus eines Angebots. Sobald ein Ereignis eintritt, sendet Fynn einen 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 unter data, daneben liegen Metadaten zum Ereignis und der Vertriebskanal als Kontext.

object

erforderlich

Metadaten zum Ereignis.

Anzeigen event

string

Eindeutige Kennung dieser Zustellung (ULID), identisch mit dem Header X-Webhook-Id. Nutze sie, um Wiederholungen idempotent zu verarbeiten.

string

Der Ereignistyp, zum Beispiel offer.expired.

string

Schema-Version des Ereignisses, aktuell v1.

string

Zeitpunkt der Auslösung im ISO-8601-Format.

object | null

Der Vertriebskanal, in dessen Kontext das Ereignis entstand. null, wenn sich kein Kanal auflösen ließ.

Anzeigen salesChannel

string

Kennung des Vertriebskanals.

string

Technischer Name des Kanals, zum Beispiel default.

string

Anzeigename der Marke.

object

erforderlich

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:

Header	Inhalt
`X-Webhook-Event`	Der Ereignistyp, zum Beispiel `offer.expired`.
`X-Webhook-Event-Version`	Schema-Version, aktuell `v1`.
`X-Webhook-Id`	Eindeutige Kennung der Zustellung, identisch mit `event.id`.
`X-Webhook-Signature`	Signatur des Bodys zur Echtheitsprüfung.
`X-Sales-Channel`	Technischer Name des Vertriebskanals, oder `default`.
`X-Tenant-Id`	Kennung deiner Organisation.

Prüfe immer die Signatur aus X-Webhook-Signature, bevor du eine Zustellung verarbeitest. So stellst du sicher, dass die Anfrage wirklich von Fynn stammt. Den Ablauf und Beispielcode findest du unter Webhooks einrichten.

Verfügbare Events

Event	Wird ausgelöst, wenn
`offer.expired`	Ein Angebot seinen Gültigkeitszeitraum überschreitet, bevor es angenommen wurde.

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:

string

Eindeutige Kennung des Angebots. Nutze sie, um über die Angebote-API den vollständigen Stand inklusive Kunde, Abonnement und Empfänger zu laden.

string

Fortlaufende Angebotsnummer, zum Beispiel AN-2026-000042.

string | null

Anzeigename des Angebots.

string

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.

string

Art des Geschäfts: new_business, expansion, renewal oder one_off.

string

Wie der Empfänger zusagt: click, esignature oder print.

string | null

Sprache des Angebots, zum Beispiel de.

string | null

Datum, bis zu dem das Angebot angenommen werden konnte (ISO 8601). Bei offer.expired liegt dieser Zeitpunkt in der Vergangenheit.

string

Zeitpunkt der ersten Veröffentlichung (ISO 8601).

boolean

Ob das Angebot vollständig unterschrieben ist.

string | null

Zeitpunkt der vollständigen Unterschrift (ISO 8601), sonst null.

boolean

Ob aus dem angenommenen Angebot automatisch ein aktives Abonnement entsteht.

string | null

Verknüpfter Deal im CRM, sofern vorhanden.

object | null

Eigene Variablen aus dem Editor als flaches Name-zu-Wert-Mapping.

object | null

Die vom Empfänger erfassten Rechnungsdaten, sofern bereits hinterlegt.

array

Die Dokument-Blöcke des Angebots (Briefkopf, Parteien, Abonnement, Texte und mehr). Den Aufbau der Blöcke findest du unter Kernkonzepte.

string | null

Prüfsumme der veröffentlichten Dokumentversion.

string | null

Prüfsumme der aktuellen Dokumentversion.

boolean

Ob seit der letzten Veröffentlichung Änderungen im Entwurf liegen.

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.

Beispiel-Payload

{
  "event": {
    "id": "01JZ8F3KQ9X7N2VYB4C6D8E0FG",
    "type": "offer.expired",
    "version": "v1",
    "createdAt": "2026-06-29T08:00:01+00:00"
  },
  "salesChannel": {
    "id": "01JH2K8M4P6R8T0V2X4Z6B8D0F",
    "name": "default",
    "brandName": "Deine Marke"
  },
  "data": {
    "offer": {
      "id": "01JZ7A2B3C4D5E6F7G8H9J0K1L",
      "number": "AN-2026-000042",
      "name": "Angebot Enterprise-Plan 2026",
      "status": "open",
      "dealType": "new_business",
      "acceptanceMode": "esignature",
      "locale": "de",
      "validUntil": "2026-06-28T23:59:59+00:00",
      "issuedAt": "2026-06-01T10:00:00+00:00",
      "signed": false,
      "signedAt": null,
      "autoActivateSubscription": true,
      "crmDealId": null,
      "customVariables": null,
      "capturedInvoiceDetails": null,
      "publishedVersionHash": "8f14e45fceea167a5a36dedd4bea2543",
      "currentVersionHash": "8f14e45fceea167a5a36dedd4bea2543",
      "hasUnpublishedChanges": false,
      "sections": [
        { "type": "letterhead", "...": "..." },
        { "type": "parties", "...": "..." },
        { "type": "subscription", "...": "..." }
      ],
      "customer": {},
      "subscription": null,
      "recipients": [
        {}
      ],
      "purchaseOrderDocument": null,
      "auditLogDocument": null,
      "signedDocument": null,
      "contactPerson": {}
    }
  }
}

Antworte mit einem 2xx-Statuscode, sobald du die Zustellung angenommen hast. Schlägt die Zustellung fehl, wiederholt Fynn sie bis zu dreimal.

Einführung

Grundlagen

Pläne

Angebote

Provisionen

Zahlungspläne

Der Envelope

HTTP-Header

Verfügbare Events

`offer.expired`

Das `offer`-Objekt

Beispiel-Payload

​Der Envelope

​HTTP-Header

​Verfügbare Events

​offer.expired

​Das offer-Objekt

​Beispiel-Payload

Der Envelope

HTTP-Header

Verfügbare Events

`offer.expired`

Das `offer`-Objekt

Beispiel-Payload