Webhook - Business OS

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"
}

Die aktuelle Webhook-URL kannst du über 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",
        "holder_name": "Mustermann GmbH",
        "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, holder_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.

​Definition

​Webhook-URL konfigurieren

​Payload-Struktur

​Event-Typen

​refresh_complete

​connection_error

​connection_destroyed

​Verbrauch

Definition

Webhook-URL konfigurieren

Payload-Struktur

Event-Typen

`refresh_complete`

`connection_error`

`connection_destroyed`

Verbrauch