---
title: "Webhooks"
slug: "best-practice"
updated: 2025-11-13T15:00:55Z
published: 2025-11-13T15:00:55Z
canonical: "help.frisbii.com/best-practice"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.frisbii.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

Ein Webhook ist in der Webentwicklung eine Methode, um das Verhalten einer Webseite oder Webanwendung mit benutzerdefinierten Callbacks zu erweitern oder zu ändern. Diese Callbacks können von Drittnutzern und Entwicklern gepflegt, geändert und verwaltet werden, die nicht unbedingt mit der ursprünglichen Website oder Anwendung verbunden sind.

## Zugriff auf Menüpunkt Webhooks

In der Navigation auf der linken Seite **Konfigurationen > Integrationen und Werkzeuge> Webhooks** anklicken.

## Webhooks-Konfiguration

1. In der rechten oberen Ecke **Konfiguration** anklicken.
2. In **Webhook-URLs** eine URL einfügen und **Hinzufügen** anklicken.
3. Einen oder mehrere [Ereignistypen](https://docs.frisbii.com/reference/getevents) auswählen. Die Folgenden stehen zur Wahl
  - Rechnungsereignisse
  - Abonnementereignisse
  - Kundenereignisse
4. Im Feld **Benachrichtungen per E-Mail** eine E-Mail-Adresse einfügen und **Hinzufügen** anklicken.
5. Einen **Benutzernamen** und ein **Passwort** in der Kachel **Anmeldeinformationen** eingeben.
6. Das **Secret** durch Klicken auf ![Reepay_Admin_-_Copy_Icon.png](https://cdn.document360.io/b84e1b5d-2ba6-4465-8c62-fb45a2f31314/Images/Documentation/167e6a9cab327a(2).png?sv=2026-02-06&spr=https&st=2026-10-26T14%3A30%3A23Z&se=2026-10-26T15%3A30%3A23Z&sr=c&sp=r&sig=RsrtomNM8MbU%2B85wmyKWLNoLF4rqqXhZOAibzavszYs%3D) kopieren.
7. Den Webhook über den **Status**-Schalter aktivieren.
8. **Speichern** anklicken.

## Erläuterung für ausstehende Webhooks

Manchmal bleiben Webhooks in der Warteschleife und es scheint, dass sie nicht einmal an den Server gesendet werden.

### First in, first out

Alle Webhooks werden in **FIFO-Reihenfolge (first in, first out) gruppiert für jeden Kunden** gesendet.

Das bedeutet, dass davon ausgegangen werden kann, dass für jeden Kunden Ereignisse in der richtigen Reihenfolge erhalten werden.

Beispiel: CUSTOMER_UPDATED wird nicht vor CUSTOMER_CREATED ankommen.

> [!NOTE]
> Hinweis
> 
> Wenn der Dienst **keinen HTTP-Code zwischen 200 und 299 zurückgibt**:
> 
> - betrachten wir den Webhook als fehlgeschlagen
> - werden wir die nächsten Webhooks für diesen Kunden blockieren

### Überlegungen zu Webhooks

- Der Endpunkt muss innerhalb von **30 Sekunden antworten**.
- Eine Antwort mit dem **HTTP-Code 2XX** gilt als erfolgreich. Alle anderen Antworten werden als **Fehlschläge** gewertet.
- Der Inhalt eines Webhooks benachrichtigt über ein Ereignis im Frisbii Payment System, die betroffenen Ressourcen und den Ereignistyp, **trägt** aber **selbst keinen Zustand in sich**. Es wird empfohlen, anschließend die API zu verwenden, um den aktualisierten Status einer Ressource zu erhalten.
- Der **Endpunkt muss idempotent sein**, d.h. mehrere Aufrufe desselben Webhooks mit demselben Ergebnis wie ein einziger Aufruf müssen möglich sein.

Dies liegt daran, dass Kommunikationsfehler zu einem Szenario führen können, in dem Frisbii Payments einen Aufruf als fehlgeschlagen betrachtet, obwohl er empfangen wurde. Wir werden fehlgeschlagene Aufrufe wiederholen. Siehe unten.
- In Fehlerszenarien können Webhooks in einer anderen Reihenfolge ankommen. Daher **immer die API verwenden, um den aktuellen Status einer Ressource** abzurufen.

Ein Beispiel dafür ist die Kündigung eines Abonnements mit anschließender Rücknahme der Kündigung. Der "Cancel"-Webhook könnte nach dem "Uncancel"-Webhook ankommen.

### Best Practices

Frisbii Payment sendet max. 10 Webhook-Anfragen zu einem Zeitpunkt an den Server.

Eine gute Praxis ist es, Ereignisse in eine lokale Warteschlange auf der Seite auszulagern und **200 OK auf jedes** zurückzugeben.

Das bedeutet, dass schnell reagiert werden kann und sich keine Ereignisse gegenseitig blockieren. Jedes Ereignis kann aus der Warteschlange verarbeitet und die Werte problemlos aktualisiert werden.

---

## Beispiele von Webhooks und deren Inhalt

`INVOICE_CREATED`

```json
{
"id":"cd614e4887c8c12ae67fbf80c3ffc1b6",
"timestamp":"2025-11-11T13:19:18.99Z",
"signature":"7718c7690b51f2c9b1cee2a173b6eb81aab2b4849e8eb8544c3a3ee2640231e1",
"invoice":"inv-52",
"subscription":"sub-0022",
"customer":"cust-0005",
"event_type":"invoice_created",
"event_id":"f131c9306108777bab8e1e0278e76480"
}
```

JSON

`INVOICE_REFUND`

```json
{
"id":"b6cfe85ab18d65d2750f093a6e59400c",
"timestamp":"2025-11-11T13:33:04.803Z",
"signature":"9674d2ff0482157d149ade9d071243df448f891e36c42dcb2fba6eaa887b7401",
"invoice":"inv-52",
"subscription":"sub-0022",
"customer":"cust-0005",
"transaction":"5ccb1455b072adf948c0e93d4a26e103",
"event_type":"invoice_refund",
"event_id":"e1d018b2fb86f62464ea219f81636598",
"credit_note":"5ccb1455b072adf948c0e93d4a26e103"
}
```

JSON

`SUBSCRIPTION_RENEWAL`

```json
{
"id":"abefe07e4a742cce106695dd8238bdcb",
"timestamp":"2025-11-11T13:19:18.99Z",
"signature":"12b4423aaf65ce0978fb0ba752d147618051fc1a9ac0f9c50377a456922848e7",
"invoice":"inv-52",
"subscription":"sub-0022",
"customer":"cust-0005",
"event_type":"subscription_renewal",
"event_id":"20127731fe4a68ef674c4d4cffcda2af"
}
```

JSON

`SUBSCRIPTION_EXPIRED`

```json
{
"id":"2585ec2c89395a515c8f47afa2920899",
"timestamp":"2025-11-11T13:33:04.738Z",
"signature":"99fcf1acddd18bad4615fd95a52934a28bc589cb5682efbe28a34fb7baf460fd",
"subscription":"sub-0022",
"customer":"cust-0005",
"event_type":"subscription_expired",
"event_id":"8ae7b7b17a5b1612ea38e9f714c9259f"
}
```

JSON

`CUSTOMER_PAYMENT_METHOD_ADDED`

```json
{
"id":"e1c69ad60688cfb4cf38ca6a6c75959a",
"timestamp":"2025-11-11T13:28:14.601Z",
"signature":"3106e26798b59a20b3b0f8135ec6fe4205c7b5e8fb62498b6d19bea82317e64c",
"customer":"cust-0005",
"event_type":"customer_payment_method_added",
"event_id":"3e17853629d60230e1178e436087b699",
"payment_method":"ca_dc1a6deb3b702b6564531ec21d1da6cf",
"payment_method_reference":"cs_4c5ad0ac03ddd97efa33d7b48ef18b9a"
}
```