> ## Documentation Index
> Fetch the complete documentation index at: https://docs.business-os.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook

> Erhalte automatische Benachrichtigungen bei neuen Kontodaten, Verbindungsfehlern oder gelöschten Verbindungen.

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

```json theme={null}
{
  "webhook_url": "https://hook.eu2.make.com/dein-webhook-pfad"
}
```

Die aktuelle Webhook-URL kannst du über `GET /v2/banking/webhook-url` abrufen.

<Warning>
  Die Webhook-URL muss eine **öffentliche HTTPS-URL** sein. Lokale Adressen (localhost, private IP-Bereiche) und nicht-HTTPS URLs werden abgelehnt.
</Warning>

## Payload-Struktur

Alle Webhook-Payloads haben dieselbe Envelope-Struktur:

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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

<Check>
  Webhooks verbrauchen keine Credits. Nur aktive API-Aufrufe (z.B. Transaktionen abrufen) werden berechnet.
</Check>