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. Als empfangender Service Provider folgt ein separater Webhook mit Topic MessageLevelStatusSent, sobald der PSB im Auftrag von Ihnen eine MLS an den sendenden SP verschickt. Nutzen Sie dieses Topic, um zu überwachen, ob Ihre eigenen ausgehenden MLS-Antworten korrekt zugestellt werden.

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

Neben spezifischen Topics können Sie auch Wildcard-Patterns verwenden, um mehrere Event-Typen mit einem Hook abzufangen.

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

Der PSB kann eine Eingangsrechnung empfangen, ohne sie an die empfangende Partei weiterzuleiten. Das Topic InvoiceReceived bedeutet, dass der PSB die Rechnung empfangen hat; ohne Hook auf diesem Topic geht nichts an einen Endpunkt.

• Keine Webhook-Fehler ist kein Beweis, dass der Hook funktioniert. HookSentError existiert nur, wenn ein Hook konfiguriert ist, der nicht zustellt.
• Ein Hook kann zwischenzeitlich entfernt worden sein. Eine frühere erfolgreiche Zustellung an dieselbe Partei/denselben Endpunkt beweist, dass der Hook existiert hat, nicht dass er jetzt noch vorhanden ist. Daher zunächst die aktuelle Hook-Konfiguration prüfen, statt dies als Ersteinrichtung zu behandeln.
• Eine Empfangsbestätigung beim Absender ist nicht dasselbe wie die Zustellung an die empfangende Software.

Beheben Sie einen fehlenden Hook, indem Sie den bestehenden Hook aktualisieren, statt ihn zu löschen und neu zu erstellen.

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.

Erste Linie: Ausfallzeit auf Kundenseite vs. technisches Problem (Akzeptanz und Produktion)

HookSentError, ein wiederholter HTTP 404 oder „Endpunkt ist offline"/„Akzeptanzumgebung ist aus" kann auch daran liegen, dass der Kunde den Akzeptanz- oder Produktionsendpunkt vorübergehend abschaltet (Entwicklung, Wartung). Das ist keine eConnect-Plattformstörung.

1. Symptom bestätigen: HookSentError, Endpunkt offline oder HTTP 404 auf dem vom Kunden konfigurierten Webhook-Endpunkt. Oft sichtbar als der exakte Text Response status code does not indicate success: 404 (Not Found) (meist eine .NET-HttpRequestException bei der ausgehenden Hook-Anfrage). Dies ist ein 404 vom Endpunkt des Kunden selbst (offline oder falscher Pfad), nicht der Peppol-Fehler PartyId not found beim Senden (SMP-404) und keine REST-Ressourcen-404 aus der Fehlerbehandlung der API.
2. Nachfragen, ob die Ausfallzeit beabsichtigt und vorübergehend ist (Entwickler/Kunde).
3. Bestätigt vorübergehend → notieren, keine weitere Aktion auf eConnect-Seite, bis der Endpunkt wieder erreichbar ist. Sobald der Endpunkt wieder 2xx liefert, können verpasste Events über den Batch-Endpunkt abgerufen werden.
4. Nicht beabsichtigt oder unbekannt → dem oben stehenden Standard-HookSentError-Runbook folgen (DNS/SSL/Timeout, Logs, Monitoring, Batch-Wiederherstellung).

• 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.