# BKV-Webhooks (https://docs.otark.com/de/developer/brp-connect-api/webhooks)

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:

```json
{
  "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.

```bash
# 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
```

<Callout type="info">
  Verifizieren Sie immer die Webhook-Signatur, bevor Sie das Payload verarbeiten, um sicherzustellen, dass die Anfrage von OES stammt.
</Callout>

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