BRP Connect API

BKV-Webhooks

Echtzeit-Ereignisbenachrichtigungen für Ereignisse in BRP Connect

Als Markdown anzeigen

Webhook-Abonnements konfiguriert der Administrator in BRP Connect. Ist ein Abonnement aktiv, sendet das System Echtzeit-Ereignisbenachrichtigungen an den registrierten Endpunkt.

Unterstützte Ereignisse

EreignisBeschreibung
nomination.gate_closure_reminderErinnerung, 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_createdEine Nominierungsdatei wurde hinzugefügt oder aktualisiert
nomination.error_detectedEin Fehler wurde in einer Nominierung erkannt
contract.addedEin neuer Vertrag wurde hinzugefügt
customer.assignedEin 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:

  1. Extrahieren Sie den Wert des X-Webhook-Signature-Headers aus der Anfrage.
  2. Berechnen Sie den HMAC-SHA256 des Roh-Request-Bodys mit Ihrem gemeinsamen Geheimnis.
  3. 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"
fi

Verifizieren 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 timestamp und 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.

Zuletzt aktualisiert am