Definition
Sobald sich der Status einer Bank-Verbindung ändert, sendet Business OS einen POST-Request an deine konfigurierte Webhook-URL. Du erhältst Benachrichtigungen bei neuen Kontodaten, Verbindungsfehlern und gelöschten Verbindungen.
Webhook-URL konfigurieren
Du kannst deine Webhook-URL über die API setzen:
PUT /v2/banking/webhook-url
{
"webhook_url": "https://hook.eu2.make.com/dein-webhook-pfad"
}
GET /v2/banking/webhook-url abrufen.
Die Webhook-URL muss eine öffentliche HTTPS-URL sein. Lokale Adressen (localhost, private IP-Bereiche) und nicht-HTTPS URLs werden abgelehnt.
Payload-Struktur
Alle Webhook-Payloads haben dieselbe Envelope-Struktur:
{
"event": "event_name",
"data": { ... },
"received_at": "2026-03-31T14:30:00.000Z"
}
| Feld | Typ | Beschreibung |
|---|
event | string | Event-Typ (siehe unten) |
data | object | Event-spezifische Daten |
received_at | string (ISO 8601) | Zeitpunkt des Events |
Event-Typen
refresh_complete
Neue Kontodaten sind verfügbar. Wird ausgelöst, wenn eine automatische oder manuelle Aktualisierung abgeschlossen wurde.
{
"event": "refresh_complete",
"data": {
"connection_id": "9182736450918273645",
"provider_name": "Musterbank",
"provider_code": "musterbank_oauth_client_de",
"country_code": "DE",
"status": "active",
"refresh_type": "automatic",
"accounts": [
{
"id": "8273645091827364509",
"name": "DE89370400440532013000",
"nature": "account",
"balance": 1250.00,
"currency_code": "EUR",
"iban": "DE89370400440532013000"
}
]
},
"received_at": "2026-03-31T14:30:00.000Z"
}
| Feld | Typ | Beschreibung |
|---|
connection_id | string | ID der aktualisierten Verbindung |
provider_name | string | Name der Bank |
provider_code | string | Technischer Provider-Code |
country_code | string | Ländercode (ISO 3166-1 alpha-2) |
status | string | Verbindungsstatus (active, inactive) |
refresh_type | string | automatic oder manual |
accounts | array | Aktuelle Kontostände (id, name, nature, balance, currency_code, iban) |
connection_error
Fehler bei einer Verbindung — z.B. abgelaufene PSD2-Einwilligung oder technisches Problem.
{
"event": "connection_error",
"data": {
"connection_id": "9182736450918273645",
"provider_name": "Musterbank",
"provider_code": "musterbank_oauth_client_de",
"country_code": "DE",
"refresh_type": "automatic",
"error_class": "InvalidCredentials",
"error_message": "Credentials are invalid."
},
"received_at": "2026-03-31T14:30:00.000Z"
}
| Feld | Typ | Beschreibung |
|---|
connection_id | string | ID der betroffenen Verbindung |
provider_name | string | Name der Bank |
provider_code | string | Technischer Provider-Code |
country_code | string | Ländercode |
refresh_type | string | automatic oder manual |
error_class | string | Fehlerklasse (z.B. InvalidCredentials, ProviderError) |
error_message | string | Fehlerbeschreibung |
connection_destroyed
Eine Verbindung wurde gelöscht — entweder durch API-Aufruf oder durch die Bank.
{
"event": "connection_destroyed",
"data": {
"connection_id": "9182736450918273645",
"provider_name": "Musterbank",
"provider_code": "musterbank_oauth_client_de",
"country_code": "DE",
"refresh_type": "automatic"
},
"received_at": "2026-03-31T14:30:00.000Z"
}
| Feld | Typ | Beschreibung |
|---|
connection_id | string | ID der gelöschten Verbindung |
provider_name | string | Name der Bank |
provider_code | string | Technischer Provider-Code |
country_code | string | Ländercode |
refresh_type | string | automatic oder manual |
Verbrauch
Webhooks verbrauchen keine Credits. Nur aktive API-Aufrufe (z.B. Transaktionen abrufen) werden berechnet.
