Webhooks

Info: Webhooks sind im Business-Tarif verfügbar.

Webhooks ermöglichen es Ihnen, Echtzeit-Benachrichtigungen zu erhalten, wenn Ereignisse in Ihrer Rekivo-Organisation auftreten. Statt die API abzufragen, registrieren Sie eine Endpunkt-URL und Rekivo sendet HTTP-POST-Anfragen, wann immer abonnierte Ereignisse eintreten.

Webhooks einrichten

Einstellungen öffnen

Navigieren Sie zum Webhooks-Bereich in Ihren Organisationseinstellungen.

Endpunkt hinzufügen

Geben Sie die URL Ihres Webhook-Empfängers ein und wählen Sie die Ereignisse aus, die Sie abonnieren möchten. Rekivo generiert ein Signaturgeheimnis für Sie.

Signaturgeheimnis speichern

Kopieren und speichern Sie das Signaturgeheimnis sicher. Sie benötigen es, um eingehende Webhook-Payloads zu verifizieren. Das Geheimnis wird nur einmal bei der Erstellung angezeigt.

Ereignisse

Sie können eine beliebige Kombination der folgenden Ereignisse abonnieren:

Ereignis	Auslöser
invoice.created	Eine neue Rechnung wird per E-Mail empfangen oder manuell hochgeladen
invoice.status_changed	Der Workflow-Status einer Rechnung ändert sich (z.B. Neu → Freigegeben)
invoice.deleted	Eine Rechnung wird gelöscht
export.completed	Ein Export-Archiv wurde fertig erstellt

Payload-Format

Alle Webhook-Zustellungen sind HTTP-POST-Anfragen mit einem JSON-Body:

{
  "event": "invoice.created",
  "timestamp": "2026-03-15T14:30:00.000Z",
  "data": {
    "invoiceId": "clx1abc...",
    "format": "XRechnung UBL",
    "sender": "Lieferant GmbH"
  }
}

Die Payload-Struktur in data variiert je nach Ereignistyp.

Signaturen verifizieren

Jede Webhook-Anfrage enthält einen X-Rekivo-Signature-Header mit einer HMAC-SHA256-Signatur des Anfrage-Bodys, signiert mit dem Geheimnis Ihres Endpunkts.

X-Rekivo-Signature: sha256=a1b2c3d4e5f6...

Um eine Webhook-Zustellung zu verifizieren:

Lesen Sie den rohen Anfrage-Body als String.
Berechnen Sie den HMAC-SHA256 des Bodys mit Ihrem Signaturgeheimnis.
Vergleichen Sie Ihre berechnete Signatur mit dem Wert im X-Rekivo-Signature-Header.

Warning: Verifizieren Sie immer die Signatur, bevor Sie einen Webhook verarbeiten. Dies stellt sicher, dass die Anfrage tatsächlich von Rekivo stammt und nicht manipuliert wurde.

Zusätzliche Header

Header	Beschreibung
X-Rekivo-Event	Der Ereignistyp (z.B. `invoice.created`)
X-Rekivo-Delivery	Eindeutige Zustellungs-ID für Idempotenz
X-Rekivo-Signature	HMAC-SHA256-Signatur des Bodys

Zustellverhalten

Rekivo wartet bis zu 10 Sekunden auf eine Antwort Ihres Endpunkts.
Eine Antwort mit einem 2xx-Statuscode gilt als erfolgreich.
Jede andere Antwort (Timeout, Verbindungsfehler, 4xx, 5xx) wird als fehlgeschlagen markiert.
Fehlgeschlagene Zustellungen werden nicht automatisch wiederholt. Sie können die Zustellhistorie einsehen und Testereignisse über die Einstellungsseite senden.

Limits

Bis zu 5 Webhook-Endpunkte pro Organisation.
Webhook-URLs müssen in der Produktion HTTPS verwenden.
Zustellungs-Payloads sind auf die ersten 1000 Zeichen der Antwort Ihres Endpunkts begrenzt (für Debugging).

Testen

Sie können ein Testereignis über die Webhook-Einstellungsseite senden, um zu überprüfen, ob Ihr Endpunkt erreichbar ist und Signaturen korrekt verifiziert. Das Testereignis verwendet den Ereignistyp invoice.created mit Beispieldaten.