Webhooks sind die primäre Methode, um Echtzeit-Benachrichtigungen vom PSB zu empfangen. Bei jedem relevanten Ereignis (eine empfangene Rechnung, eine Statusänderung, eine Zustellbestätigung) sendet der PSB eine HTTP POST-Anfrage an Ihren Endpoint mit den Details des Events.

Sie registrieren einen Webhook (einen "Hook") im PSB mit einer URL und einem Topic. Der PSB sendet dann alle Events für dieses Topic an Ihre URL. Jedes Event enthält die relevanten Daten als JSON-Payload.

Registrieren Sie einen Hook über die API:

POST /api/v1/hook

Die wichtigsten Konfigurationselemente:

Möchten Sie einem bestehenden Hook ein weiteres Topic (z. B. InvoiceReceived) hinzufügen? Aktualisieren Sie die bestehende Webhook-Konfiguration über die reguläre /hook-API, sodass das gewünschte Topic im topics-Array enthalten ist:

{
  "topics": ["InvoiceReceived"]
}

Aktualisieren Sie den bestehenden Hook, anstatt ihn zu löschen und neu anzulegen. Löschen und Neuanlegen führt zu einer Race Condition, bei der Events vorübergehend nicht zugestellt werden können (siehe Warnung oben).

MLS (Message Level Status) ist der Nachfolger des älteren MLR und gibt der sendenden Partei Feedback über den Empfang und die Verarbeitung eines Dokuments. MLS ist nicht standardmäßig aktiviert und muss pro Party über die reviews-Capability in der SMP-Konfiguration konfiguriert werden. Sobald MLS aktiviert ist, handhabt der PSB es automatisch: als empfangender Service Provider sendet der PSB eine MLS-Nachricht an den Absender zurück nach Empfang und Zustellung.

Wenn Sie selbst Dokumente über den PSB versenden, erhalten Sie MLS-Feedback von der empfangenden Partei als Webhook-Event zum Topic MessageLevelStatusReceived. Der Payload enthält unter anderem:

Um MLS-Nachrichten zu empfangen, muss der Peppol-Hook das Feld mlsType enthalten. Die möglichen Werte sind ALWAYS_SEND (immer MLS zurücksenden) und FAILURE_ONLY (nur bei Ablehnungen).

Tipp: Das vollständige MLS-Dokument können Sie über GET /api/v1-beta/{partyId}/generic/{documentId}/download abrufen, aber der Webhook-Payload enthält in der Regel ausreichend Informationen.

Der PSB sichert alle Webhook-Zustellungen mit HMAC SHA256-Signaturen. Bei jeder Anfrage sendet der PSB den Header:

X-EConnect-Signature: sha256={Signatur}

Um die Signatur zu verifizieren:

1. Nehmen Sie den rohen JSON-Payload der Anfrage.
2. Berechnen Sie den HMAC SHA256-Hash mit Ihrem geheimen Schlüssel (derselbe, den Sie beim Erstellen des Hooks angegeben haben).
3. Vergleichen Sie Ihren berechneten Hash mit dem Wert im X-EConnect-Signature-Header.
4. Wenn sie übereinstimmen, ist die Anfrage authentisch.

Prüfen Sie auch das sentOn-Feld im Payload. Wenn dieser Zeitstempel älter als 5 Minuten ist, lehnen Sie die Anfrage ab. Dies verhindert Replay-Attacks, bei denen eine abgefangene Anfrage später erneut abgespielt wird.

Neben der HMAC-Verifizierung bietet der PSB zusätzliche Sicherheitsebenen:

• IP-Whitelisting: Beschränken Sie eingehende Anfragen auf die PSB-Produktions-IPs (104.40.188.59 und 104.47.148.207)
• OAuth Webhook-Authentifizierung: Der PSB kann sich bei Ihrem Endpoint mit OAuth2-Credentials authentifizieren
• Mutual SSL: Verwenden Sie Client-Zertifikate für gegenseitige TLS-Authentifizierung

Wenn Sie mehrere Hooks konfiguriert haben, bestimmt der PSB den zu verwendenden Hook anhand folgender Kriterien:

1. PartyId-Level-Hooks haben Vorrang vor Environment-Level-Hooks
2. Spezifische Topics haben Vorrang vor Wildcards
3. Wenn mehrere Hooks mit Filtern auf dasselbe Topic zutreffen: Der längste Filter (nach Zeichenanzahl) gewinnt -- ein Filter mit einer zusätzlichen &&-Klausel gewinnt beispielsweise gegen einen kürzeren Filter ohne diese Klausel. So wird eine doppelte Zustellung vermieden, ohne dass Filter sich gegenseitig ausschliessen müssen.
4. Bei gleicher Priorität: Hook-ID als Tiebreaker

Nachfolgend sind häufige Webhook-Probleme und deren Lösungen aufgeführt.

Der PSB sendet Webhook-Events (z.B. InvoiceReceived bei einer eingegangenen E-Rechnung) an den konfigurierten Endpunkt. Ist dieser Endpunkt nicht erreichbar — durch ein Timeout, einen SSL-Fehler oder einen DNS-Fehler wie No such host is known — wiederholt der PSB mit exponentiellem Backoff für 5 Tage (Timeout 100 Sek. pro Versuch). Bei jedem Versuch wird ein HookSentRetry-Event gesendet; nach 5 Tagen ohne 2xx-Antwort folgt HookSentError als Abschlussstatus und der PSB stellt die Versuche ein.

Folge: Eine eingegangene E-Rechnung wird nicht an den Kunden weitergeleitet, solange der Endpunkt nicht erreichbar ist, ohne dass der Kunde dies direkt bemerkt. Empfohlene Maßnahmen:

• Monitoring einrichten: Einen Hook (z.B. einen Mail-Hook) für das Topic HookSentError abonnieren, damit ein endgültiger Zustellungsfehler aktiv gemeldet wird statt unbemerkt zu bleiben. Optional auch HookSentRetry für frühzeitige Erkennung.
• Grundursache beheben: Bei einem DNS-Fehler den DNS-Eintrag des Endpunkt-Domainnamens prüfen und wiederherstellen; bei Timeouts den Endpunkt schneller antworten lassen (2xx innerhalb von 100 Sek., aufwändige Verarbeitung asynchron).
• Fehlende Events wiederherstellen: Events, die während der Auszeit fehlgeschlagen sind, können über den Batch-Endpunkt nachgeholt werden. Das 5-tägige Retry-Fenster bedeutet, dass rechtzeitige Behebung innerhalb dieses Zeitraums reguläre Zustellung noch ermöglicht.

• Verwenden Sie immer HTTPS für Ihren Webhook-Endpoint
• Implementieren Sie idempotente Verarbeitung: In seltenen Fällen kann der PSB ein Event mehrfach zustellen
• Geben Sie schnell einen 2xx-Statuscode zurück: Der PSB betrachtet jede Nicht-2xx-Antwort als Fehler und versucht das Event erneut
• Protokollieren Sie alle empfangenen Events für Debugging und Auditing
• Verwenden Sie ein Queue-System auf Ihrer Seite, wenn die Verarbeitung Zeit benötigt; bestätigen Sie zuerst den Empfang und verarbeiten Sie danach

Möchten Sie Dokumente lieber in großen Mengen abrufen? Sehen Sie sich Batch Hooks an.