BKV-Webhooks
Echtzeit-Ereignisbenachrichtigungen für Ereignisse in BRP Connect
Webhook-Abonnements konfiguriert der Administrator in BRP Connect. Ist ein Abonnement aktiv, sendet das System Echtzeit-Ereignisbenachrichtigungen an den registrierten Endpunkt.
Unterstützte Ereignisse
| Ereignis | Beschreibung |
|---|---|
nomination.gate_closure_reminder | Erinnerung, dass die Gate Closure des Fahrplanmanagements naht: weniger als 8 h verbleibend und die Nominierung ist noch nicht bestätigt — Status pending oder partial_match. match und superseded lösen nicht aus |
nomination.file_created | Eine Nominierungsdatei wurde hinzugefügt oder aktualisiert |
nomination.error_detected | Ein Fehler wurde in einer Nominierung erkannt |
contract.added | Ein neuer Vertrag wurde hinzugefügt |
customer.assigned | Ein neuer Kunde wurde dem BKV zugewiesen |
Payload-Format
Alle Webhook-Payloads folgen dieser Struktur:
{
"event": "nomination.error_detected",
"timestamp": "2026-07-14T12:35:00Z",
"data": { ... }
}Das Feld data enthält ereignisspezifische Details. Der timestamp ist der Zeitpunkt des Ereignisses (ISO 8601, UTC).
Signaturverifizierung
Payloads werden mit HMAC-SHA256 und einem gemeinsamen Geheimnis signiert. Die Signatur wird im X-Webhook-Signature-Header übermittelt.
So verifizieren Sie ein Webhook-Payload:
- Extrahieren Sie den Wert des
X-Webhook-Signature-Headers aus der Anfrage. - Berechnen Sie den HMAC-SHA256 des Roh-Request-Bodys mit Ihrem gemeinsamen Geheimnis.
- Vergleichen Sie die berechnete Signatur mit dem Header-Wert.
# Beispiel: Webhook-Signatur verifizieren
SIGNATURE=$(echo -n "$REQUEST_BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')
if [ "$SIGNATURE" = "$RECEIVED_SIGNATURE" ]; then
echo "Gültige Signatur"
fiVerifizieren Sie immer die Webhook-Signatur, bevor Sie das Payload verarbeiten, um sicherzustellen, dass die Anfrage von OES stammt.
Best Practices
- Schnell antworten: Senden Sie innerhalb weniger Sekunden einen
200-Statuscode zurück. Verarbeiten Sie das Ereignis bei Bedarf asynchron. - Duplikate behandeln: Ereignisse können mehrfach zugestellt werden. Verwenden Sie
timestampund Ereignisdaten zur Deduplizierung. - Fehler überwachen: Wenn Ihr Endpunkt nicht antwortet, wiederholt OES die Zustellung mit exponentiellem Backoff — bis zu fünf Versuche innerhalb von 24 Stunden ab dem Ereignis. Danach bricht OES die Zustellung ab; der Endpunkt bleibt eingerichtet und erhält die folgenden Ereignisse. Verloren geht dabei nichts: Nominierungen und Transaktionen sind mit Status und Version jederzeit über die API abrufbar — der Webhook ist die Benachrichtigung, nicht die Quelle.
SFTP-Server
Verbindung und Nutzung des Otark-SFTP-Servers für BKV-Nominierungsexporte
/contracts GET
Die Verträge auflisten, auf die der angemeldete BKV Zugriff hat. Filterbar nach Status, Typ, EIC-Code, Lieferzeitraum und dem Tag, an dem der Vertrag gilt. Erforderlicher Scope: contracts:read
Zuletzt aktualisiert am