---
title: API-Schlüssel und Webhooks – Benutzerhandbuch
slug: api-schlussel-und-webhooks-benutzerhandbuch
createdAt: 2026-11-18T09:33:40.584Z
---

Dieses Handbuch erklärt, wie Sie Ihr Hotel mit anderen Programmen verbinden: mit **API-Schlüsseln** und **Webhooks**. Es richtet sich an Hoteliers und Administratorinnen und Administratoren – Programmierkenntnisse brauchen Sie nicht.

:::hint{type="info"}
Für Ihre IT oder Ihren Software-Dienstleister gibt es eine eigene, technische Dokumentation. Sie ist mit einem Passwort geschützt. Die Zugangsdaten finden Sie in der Software auf der Seite API-Schlüssel (siehe Abschnitt 4.1). Geben Sie sie einfach an die Person weiter, die die Verbindung technisch umsetzt.
:::

***

## 1. Kurz erklärt: Was sind eine API und Webhooks?

### Die API – die „Durchreiche“ Ihres Hotels

Stellen Sie sich die Durchreiche zwischen Küche und Restaurant vor: Das Service-Personal muss nicht in die Küche gehen. Es gibt eine Bestellung durch die Durchreiche und bekommt das fertige Gericht zurück.

Eine **API** (Programmierschnittstelle) ist so eine Durchreiche – nur für Programme. Ein anderes Programm, zum Beispiel die Buchungsstrecke auf Ihrer Website, fragt über die API bei Ihrer Hotelsoftware an: *„Welche Zimmer sind vom 12. bis 15. Mai frei und was kosten sie?“* Die Hotelsoftware antwortet automatisch. Niemand muss Daten abtippen, exportieren oder per E-Mail verschicken.

Über die API kann ein Programm – je nach Erlaubnis – Daten **lesen** (z. B. Reservierungen, Preise, Zimmer) oder **ändern** (z. B. eine Reservierung anlegen oder Preise anpassen).

### Der API-Schlüssel – eine Schlüsselkarte für Programme

Damit nicht jedes beliebige Programm an Ihre Daten kommt, braucht es einen **API-Schlüssel**. Er funktioniert wie eine Zimmer-Schlüsselkarte:

- Sie **öffnet nur bestimmte Türen**: Sie legen fest, was das Programm darf (die *Berechtigungen*).
- Sie kann ein **Ablaufdatum** haben.
- Sie lässt sich **sperren**, wenn sie nicht mehr gebraucht wird oder verloren gegangen ist.
- Für jeden Partner gibt es **eine eigene Karte**. So können Sie einem einzelnen Partner den Zugang entziehen, ohne die anderen zu stören.

### Webhooks – „Wir melden uns, sobald sich etwas ändert“

Stellen Sie sich vor, Sie warten auf ein Paket. Sie könnten alle fünf Minuten an der Rezeption fragen, ob es schon da ist. Einfacher ist es, wenn die Rezeption Sie **anruft, sobald das Paket ankommt**.

Ein **Webhook** ist genau dieser Anruf – zwischen Programmen. Sobald in Ihrem Hotel etwas passiert (eine neue Reservierung, ein Gast schließt den Online-Check-in ab, eine Zahlung geht ein), schickt die Hotelsoftware **sofort eine kurze Nachricht** an ein anderes System. Das andere System muss also nicht ständig nachfragen.

### Wie beides zusammenspielt

Webhooks und API arbeiten Hand in Hand:

1. **Etwas passiert** – zum Beispiel wird eine Reservierung geändert.
2. **Der Webhook meldet es** – kurz und ohne persönliche Details: *„Reservierung 4711 wurde geändert, und zwar das Abreisedatum.“*
3. **Das andere System holt sich die Details über die API** – mit seinem eigenen API-Schlüssel und nur, soweit es dafür berechtigt ist.

Diese Aufteilung schützt die Daten Ihrer Gäste: Die Benachrichtigung selbst enthält keine sensiblen Daten. Deshalb setzen Webhooks auch immer das Zusatzmodul *API* voraus.

### Typische Einsatzbeispiele

| Beispiel                                                                             | Was wird genutzt?                                                                                                                     |
| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| Ihre Website zeigt freie Zimmer und Preise und nimmt Buchungen direkt an.            | API (Preise abfragen, Reservierungen anlegen)                                                                                         |
| Ihr Controlling-Tool lädt jeden Morgen die Reservierungen und Berichte.              | API (nur lesen)                                                                                                                       |
| Ihr Shuttle-Service bekommt automatisch Bescheid, wenn sich eine Anreisezeit ändert. | Webhook + API                                                                                                                         |
| Ihr Türschließ- oder Gäste-App-Anbieter reagiert sofort auf Anreise und Abreise.     | Webhook + API                                                                                                                         |
| Ein KI-Assistent beantwortet Fragen wie „Wie viele Anreisen haben wir morgen?“.      | API über MCP (siehe [4.8](https://docs.hotelsoftware.io/api-schlussel-und-webhooks-benutzerhandbuch#48-ki-assistenten-verbinden-mcp)) |

***

## 2. Voraussetzungen

| Was                      | API-Schlüssel               | Webhooks                 |
| ------------------------ | --------------------------- | ------------------------ |
| **Zusatzmodul (Lizenz)** | *API*                       | *API* **und** *Webhooks* |
| **Benutzerrecht**        | *Benutzer erstellen/ändern* | *Administrator*          |

- Das Zusatzmodul schaltet Ihnen unser Support- bzw. Vertriebsteam frei.
- Das Recht *Benutzer erstellen/ändern* muss Ihrem Benutzer **ausdrücklich** zugewiesen sein – auch wenn Sie Administrator sind. API-Schlüssel sind so mächtig wie Benutzerkonten, deshalb gilt hier dieselbe Regel.
- Beide Funktionen sind mit **β-Version** gekennzeichnet. Sie sind voll nutzbar, werden aber noch weiterentwickelt. Kleinere Änderungen an Aussehen und Abläufen sind möglich.

:::BlockQuote
**Sie sehen die Menüpunkte nicht?** Dann fehlt entweder das Zusatzmodul oder das passende Benutzerrecht. Wenden Sie sich an eine Person mit Administratorrechten in Ihrem Betrieb oder an unseren Support.
:::

***

## 3. So finden Sie die Funktionen

1. Klicken Sie in der linken Leiste auf das **Werkzeug-Symbol** (*Einstellungen*).
2. Wählen Sie im aufgeklappten Menü ganz unten **Schnittstellen**.

::Image[]{src="https://api.archbee.com/api/optimize/DSrqrXX2Q_LF7hXTs8l01/fOAj7uGkleauWcfU2ziqX_01-menue-einstellungen.png" size="30" isUploading="false" width="1040" height="1908" darkWidth="1040" darkHeight="1908" showCaption="false"}

3. In der Übersicht der Schnittstellen finden Sie unter *Weitere* die Einträge **API-Schlüssel** und **Webhooks**. Sie stehen auch in der linken Leiste.

![](https://api.archbee.com/api/optimize/DSrqrXX2Q_LF7hXTs8l01/N3jBvqV7YF6uA7zHia7_Y_02-schnittstellen-uebersicht.png)

Welche weiteren Einträge Sie sehen, hängt von den Zusatzmodulen Ihres Hotels ab.

***

## 4. API-Schlüssel verwalten

### 4.1 Die Seite im Überblick

![](https://api.archbee.com/api/optimize/DSrqrXX2Q_LF7hXTs8l01/wxLHnRKs3m2unkdite1VP_03-api-schluessel-seite.png)

Die Seite besteht aus mehreren Bereichen:

| Bereich                               | Wozu?                                                                                                                                                                                                               |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Endpunkte → REST-Basis-URL**        | Die Adresse, unter der andere Programme Ihr Hotel erreichen. Diese Adresse braucht Ihr Dienstleister zusammen mit dem API-Schlüssel. Mit dem Kopier-Symbol rechts kopieren Sie sie in die Zwischenablage.           |
| **MCP (KI-Assistenten)**              | Nur sichtbar, wenn Ihr Hotel dafür freigeschaltet ist. Siehe [4.8](https://docs.hotelsoftware.io/api-schlussel-und-webhooks-benutzerhandbuch#48-ki-assistenten-verbinden-mcp).                                      |
| **API-Dokumentation**                 | Adresse, Benutzername und Passwort der **technischen Dokumentation**. Geben Sie diese Daten an Ihre IT oder Ihren Dienstleister weiter. Der Zugang gilt, solange Ihr Hotel aktiv ist und das Zusatzmodul *API* hat. |
| **Liste der Schlüssel**               | Eine Karte pro API-Schlüssel (siehe [4.4](https://docs.hotelsoftware.io/api-schlussel-und-webhooks-benutzerhandbuch#44-die-schlsselliste-lesen)).                                                                   |
| **Blauer Plus-Button** (unten rechts) | Einen neuen API-Schlüssel erstellen.                                                                                                                                                                                |

### 4.2 Einen neuen API-Schlüssel erstellen

:::hint{type="info"}
**Tipp:** Erstellen Sie für **jeden Partner und jeden Zweck einen eigenen Schlüssel** – zum Beispiel einen für die Website und einen für das Controlling. So sehen Sie später genau, wer was nutzt, und können einzelne Zugänge gezielt sperren.
:::

1. Klicken Sie unten rechts auf den **blauen Plus-Button**. Das Fenster *API-Schlüssel erstellen* öffnet sich.
2. Füllen Sie die Felder aus:

![](https://api.archbee.com/api/optimize/DSrqrXX2Q_LF7hXTs8l01/fFF_sY-xjK-MfVE91ijJq_04-api-schluessel-erstellen.png)

| Feld                     | Bedeutung                                                                                                                                            | Empfehlung                                                                                     |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| **Name** *(Pflicht)*     | Wofür bzw. für wen der Schlüssel ist. Nur für Sie zur Orientierung.                                                                                  | Partner und Zweck nennen, z. B. „Gästeliste für Shuttle-Service“.                              |
| **Läuft ab**             | Ab diesem Tag funktioniert der Schlüssel nicht mehr. Leer = kein Ablaufdatum. Das Datum lässt sich später jederzeit verlängern.                      | Für befristete Projekte und Testphasen immer ein Datum setzen.                                 |
| **Erlaubte IP-Adressen** | Der Schlüssel funktioniert nur, wenn die Anfrage von einer dieser Internet-Adressen kommt. Eine Adresse pro Zeile, höchstens 20. Leer = von überall. | Wenn Ihr Dienstleister feste Adressen nennen kann: unbedingt eintragen. Fragen Sie ihn danach. |

3. Wählen Sie die **Berechtigungen** aus (Schalter nach rechts = erlaubt). Scrollen Sie dazu im Fenster nach unten. Unter jedem Schalter steht in Klartext, was er erlaubt.

![](https://api.archbee.com/api/optimize/DSrqrXX2Q_LF7hXTs8l01/WFyXZ2jN0CJNDKvMFeNRO_05-api-schluessel-berechtigungen.png)

Die Berechtigungen sind nach Themen gruppiert. Grundsätzlich gilt: **`read`** heißt *nur lesen*, **`write`** heißt *anlegen und ändern*.

| Gruppe                                   | Was darf das Programm?                                                                                                         |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Stammdaten, Preise und Verfügbarkeit** | Hoteldaten, Zimmer und Zimmertypen, Tagespreise und Restriktionen, Sperren und Out-of-Order, Verfügbarkeit und Preise abfragen |
| **Reservierungen und Gäste**             | Reservierungen, Gästeprofile, Meldeblätter, Anfragen und Angebote                                                              |
| **Zahlungen**                            | Folios, Zahlungen, Rechnungen und Zahlungsanforderungen                                                                        |
| **Berichte**                             | Berichte bzw. Finanzberichte abrufen oder erstellen lassen                                                                     |
| **Benutzer**                             | Benutzer lesen; Passwort-Reset für Benutzer anfordern                                                                          |

Mit **Alle auswählen** und **Alle abwählen** schalten Sie alle Berechtigungen auf einmal ein oder aus.

:::hint{type="warning"}
**Geben Sie nur, was wirklich gebraucht wird.** Ein Controlling-Tool braucht in der Regel nur Lese-Rechte. Fragen Sie Ihren Dienstleister, welche Berechtigungen er benötigt.
:::

:::hint{type="info"}
Ein Schalter ist grau und lässt sich nicht einschalten? Darunter steht dann „Ihnen fehlt die dafür nötige Rolle“. Sie können einem Schlüssel nur erlauben, was Sie selbst dürfen. Für Finanzberichte brauchen Sie zum Beispiel selbst das Benutzerrecht Finanzielle Berichte.
:::

4. Klicken Sie ganz unten im Fenster auf **API-Schlüssel erstellen**. Der Button ist erst aktiv, wenn ein Name eingetragen und mindestens eine Berechtigung ausgewählt ist.

### 4.3 Den neuen Schlüssel sicher weitergeben

Nach dem Erstellen erscheint oben auf der Seite die Karte **Ihr neuer API-Schlüssel**:

![](https://api.archbee.com/api/optimize/DSrqrXX2Q_LF7hXTs8l01/_f2NNOMWV4kafMAxYl3n6_06-api-schluessel-einmalig-sichtbar.png)

:::hint{type="warning"}
**Wichtig: Der vollständige Schlüssel wird nur dieses eine Mal angezeigt.** Aus Sicherheitsgründen speichern wir ihn nicht lesbar. Wenn Sie die Seite verlassen oder auf Fertig klicken, ist er nicht mehr abrufbar – auch nicht für unseren Support.
:::

So gehen Sie vor:

1. Kopieren Sie den Schlüssel mit dem **Kopier-Symbol** rechts neben dem Feld.
2. Legen Sie ihn sofort an einem sicheren Ort ab, z. B. in einem Passwort-Manager, oder übergeben Sie ihn direkt Ihrem Dienstleister.
3. Klicken Sie auf **Fertig**.

**Sicher weitergeben heißt:**

- **Nicht** unverschlüsselt per E-Mail, Chat oder SMS verschicken. Besser: über einen Passwort-Manager teilen oder in zwei Teilen über zwei verschiedene Wege übermitteln.
- Den Schlüssel **nie** auf einer Website, in einer App oder in einem öffentlich einsehbaren Dokument veröffentlichen.
- Ihr Dienstleister braucht zusätzlich die **REST-Basis-URL** und die Zugangsdaten zur **technischen Dokumentation** (beides auf derselben Seite).

Ist Ihr Hotel für KI-Assistenten freigeschaltet, sehen Sie hier außerdem einen fertigen **Befehl für Claude Code**, der den neuen Schlüssel bereits enthält (siehe 4.8).

:::hint{type="info"}
**Schlüssel verloren?** Das ist kein Problem: Erstellen Sie einen neuen Schlüssel, tragen Sie ihn beim Partner ein und widerrufen Sie danach den alten (siehe 4.6).
:::

### 4.4 Die Schlüsselliste lesen

Jeder vorhandene Schlüssel erscheint als eigene Karte:

![](https://api.archbee.com/api/optimize/DSrqrXX2Q_LF7hXTs8l01/Ev10vpmiUn9EZYenOsI5i_07-api-schluessel-liste.png)

| Feld                     | Bedeutung                                                                                                                                                         |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Schlüssel**            | Nur der Anfang des Schlüssels (z. B. `shms_live_8Kq2…`). So können Sie ihn mit dem Schlüssel beim Partner abgleichen, ohne dass der ganze Schlüssel sichtbar ist. |
| **Berechtigungen**       | Was der Schlüssel darf.                                                                                                                                           |
| **Zuletzt verwendet**    | Wann zuletzt ein Programm mit diesem Schlüssel zugegriffen hat. *Nie* = noch nie benutzt.                                                                         |
| **Läuft ab**             | Ablaufdatum oder *Kein Ablaufdatum*.                                                                                                                              |
| **Erlaubte IP-Adressen** | Die erlaubten Adressen oder *Alle*.                                                                                                                               |

**Markierungen auf einer Karte:**

- **Deaktiviert** – der Schlüssel ist ausgeschaltet und wird abgelehnt. Er bleibt aber erhalten und kann über *Bearbeiten* wieder eingeschaltet werden.
- **Abgelaufen** – das Ablaufdatum ist überschritten. Verlängern Sie es über *Bearbeiten*, wenn der Schlüssel weiter gebraucht wird.
- **Orangefarbener Hinweis „Automatisch deaktiviert …“** – der Schlüssel wurde **90 Tage lang nicht verwendet** und deshalb automatisch ausgeschaltet. Ungenutzte Zugänge sind ein Sicherheitsrisiko. Brauchen Sie ihn noch, schalten Sie ihn über *Bearbeiten* wieder ein. Sonst widerrufen Sie ihn.

Pro Konto können höchstens **20 Schlüssel** gleichzeitig bestehen. Widerrufen Sie Schlüssel, die Sie nicht mehr brauchen.

### 4.5 Einen Schlüssel bearbeiten, deaktivieren oder verlängern

Klicken Sie auf der Karte des Schlüssels auf **Bearbeiten**.

![](https://api.archbee.com/api/optimize/DSrqrXX2Q_LF7hXTs8l01/vKzEE6SWyibqismulr4fJ_08-api-schluessel-bearbeiten.png)

Sie können ändern:

- **Name**
- **Läuft ab** – verlängern, verkürzen oder mit dem kleinen **×** entfernen
- **Erlaubte IP-Adressen**
- **Aktiv** – Schalter aus = der Schlüssel wird sofort abgelehnt, bleibt aber erhalten. Ideal, wenn Sie einen Zugang vorübergehend stoppen möchten.
- **Berechtigungen** – hinzufügen oder entfernen

Klicken Sie anschließend auf **Speichern**. Die Änderungen gelten sofort, der Partner muss nichts tun.

:::hint{type="info"}
Der Schlüssel selbst bleibt beim Bearbeiten gleich und wird **nicht** erneut angezeigt.
:::

### 4.6 Einen Schlüssel widerrufen

Widerrufen heißt: Der Schlüssel wird **endgültig ungültig** und verschwindet aus der Liste. Das lässt sich nicht rückgängig machen.

1. Klicken Sie auf der Karte des Schlüssels oben rechts auf das **×**.
2. Lesen Sie die Sicherheitsabfrage. Der Button zum Bestätigen zeigt zuerst einige Sekunden lang *Warten* – das schützt vor versehentlichem Löschen.
3. Klicken Sie auf **Okay**.

![](https://api.archbee.com/api/optimize/DSrqrXX2Q_LF7hXTs8l01/ishqesEuSSP-kT9y2tSm4_09-api-schluessel-widerrufen.png)

:::hint{type="info"}
**Achtung:** Jedes Programm, das diesen Schlüssel verwendet, funktioniert **sofort nicht mehr**. Wenn Sie nur pausieren möchten, schalten Sie den Schlüssel stattdessen über Bearbeiten → Aktiv aus.
:::

### 4.7 Was tun, wenn …

| Situation                                                       | Was Sie tun                                                                                                                                        |
| --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| … der Schlüssel verloren gegangen ist                           | Neuen Schlüssel erstellen, beim Partner eintragen lassen, alten widerrufen.                                                                        |
| … Sie den Dienstleister wechseln oder die Zusammenarbeit endet  | Den Schlüssel dieses Partners widerrufen.                                                                                                          |
| … Sie vermuten, dass ein Schlüssel in falsche Hände geraten ist | Sofort widerrufen (oder zumindest deaktivieren) und einen neuen erstellen. Prüfen Sie bei *Zuletzt verwendet*, ob der Schlüssel noch benutzt wird. |
| … eine Verbindung plötzlich nicht mehr funktioniert             | Auf der Karte prüfen: *Deaktiviert*? *Abgelaufen*? Fehlen Berechtigungen? Haben sich die IP-Adressen des Partners geändert?                        |
| … eine Mitarbeiterin oder ein Mitarbeiter das Haus verlässt     | Schlüssel laufen unabhängig von Benutzerkonten weiter. Prüfen Sie, ob die Person Schlüssel kannte, und tauschen Sie diese gegebenenfalls aus.      |

### 4.8 KI-Assistenten verbinden (MCP)

*Dieser Bereich ist nur sichtbar, wenn Ihr Hotel dafür freigeschaltet ist.*

**MCP** ist eine Art „Steckdose“ für KI-Assistenten wie Claude. Damit kann ein Assistent direkt mit Ihrer Hotelsoftware arbeiten und z. B. Fragen beantworten wie *„Welche Gäste reisen morgen an?“* oder *„Wie ist die Auslastung nächste Woche?“*.

- Der Assistent braucht dafür die **MCP-URL** von der Seite *API-Schlüssel* und einen **API-Schlüssel**.
- Der Assistent kann **genau das, was die Berechtigungen des Schlüssels erlauben** – nicht mehr.
- Für technisch versierte Nutzer steht ein fertiger **Befehl für Claude Code** zum Kopieren bereit.

:::hint{type="warning"}
**Empfehlung:** Erstellen Sie für KI-Assistenten einen **eigenen Schlüssel** – wenn möglich nur mit Lese-Rechten. So kann der Assistent Auskunft geben, aber nichts versehentlich ändern.
:::

***

## 5. Webhooks einrichten

### 5.1 Die Seite im Überblick

Öffnen Sie *Einstellungen → Schnittstellen → **Webhooks***.

![](https://api.archbee.com/api/optimize/DSrqrXX2Q_LF7hXTs8l01/vkNRQoAsG4QpP76w6GBUO_10-webhooks-seite.png)

Auf der Seite selbst gibt es nur zwei Buttons:

- **Webhooks verwalten** – öffnet das **Webhook-Portal**. Dort richten Sie alles Weitere ein.
- **Testereignis senden** – schickt eine Test-Nachricht an Ihre Empfänger (siehe [5.4](#54-die-verbindung-testen)).

### 5.2 Das Webhook-Portal öffnen

1. Klicken Sie auf **Webhooks verwalten**.
2. Das Portal öffnet sich in einem **neuen Browser-Tab**.

Gut zu wissen:

- Der Zugang zum Portal gilt aus Sicherheitsgründen **nur kurz**. Ist er abgelaufen, öffnen Sie das Portal einfach erneut über **Webhooks verwalten**.
- Blockiert Ihr Browser den neuen Tab, erscheint stattdessen das Fenster *„Das Webhook-Portal ist bereit“*. Klicken Sie dort auf **Öffnen**.
- Die Einstellungen im Portal gelten **pro Hotel**. Haben Sie mehrere Hotels, richten Sie die Empfänger in jedem Hotel eigens ein.

Im Portal verwalten Sie:

- die **Empfänger** – also wohin die Nachrichten gehen,
- die **Ereignisse** – also worüber jeder Empfänger informiert wird,
- die **Signatur-Schlüssel** – damit der Empfänger prüfen kann, dass eine Nachricht wirklich von uns kommt,
- das **Zustellprotokoll** der letzten 14 Tage.

### 5.3 Einen Empfänger anlegen

Ein **Empfänger** ist das System, das die Nachrichten bekommen soll – zum Beispiel die Software Ihres Shuttle-Dienstes. Die technischen Angaben dafür bekommen Sie von dem Partner, der die Nachrichten empfangen möchte.

1. Legen Sie im Portal einen **neuen Empfänger** an.
2. Wählen Sie die **Art des Empfängers**. Ihr Partner sagt Ihnen, welche er braucht:
   - **https-Adresse** – der häufigste Fall. Der Partner nennt Ihnen eine Internet-Adresse, die mit `https://` beginnt.
   - **AWS SQS** oder **Amazon EventBridge** – für Partner, die mit Amazon Web Services arbeiten. Die nötigen Angaben bekommen Sie ebenfalls vom Partner.
3. Wählen Sie die **Ereignisse**, über die dieser Empfänger informiert werden soll (siehe [5.6](#56-welche-ereignisse-gibt-es)). Wählen Sie nur, was der Partner wirklich braucht.

:::hint{type="info"}
**Tipp:** Wählen Sie zusätzlich das Ereignis `webhook.test`. Dann können Sie die Verbindung jederzeit mit dem Button Testereignis senden prüfen.
:::

4. Speichern Sie den Empfänger.
5. Geben Sie dem Partner den **Signatur-Schlüssel** (beginnt mit `whsec_…`), den das Portal für diesen Empfänger anzeigt. Damit kann sein System prüfen, dass eine Nachricht echt ist und unterwegs nicht verändert wurde. Behandeln Sie diesen Signatur-Schlüssel genauso vertraulich wie einen API-Schlüssel.

Damit der Partner die Details zu einem Ereignis abrufen kann (z. B. die Daten einer geänderten Reservierung), braucht er in der Regel zusätzlich einen **API-Schlüssel** mit den passenden Lese-Rechten (siehe [4.2](#42-einen-neuen-api-schlüssel-erstellen)).

### 5.4 Die Verbindung testen

1. Wechseln Sie zurück in die Hotelsoftware auf die Seite **Webhooks**.
2. Klicken Sie auf **Testereignis senden**.

![](https://api.archbee.com/api/optimize/DSrqrXX2Q_LF7hXTs8l01/I9-_kVvI2L9MWogyfciJ6_11-webhooks-testereignis.png)

| Meldung                                                                     | Bedeutung                                                                                                                              |
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| *„Testereignis an X Empfänger gesendet. Das Ergebnis siehst du im Portal.“* | Die Test-Nachricht wurde auf den Weg gebracht. Ob sie beim Empfänger angekommen ist, sehen Sie im Zustellprotokoll des Portals.        |
| *„Kein Empfänger hat das Testereignis (webhook.test) abonniert.“*           | Bei keinem Empfänger ist das Ereignis `webhook.test` ausgewählt. Ergänzen Sie es im Portal (siehe [5.3](#53-einen-empfänger-anlegen)). |

### 5.5 Das Zustellprotokoll prüfen

Im Portal sehen Sie für jeden Empfänger, welche Nachrichten in den **letzten 14 Tagen** verschickt wurden und ob sie angekommen sind.

- Ist ein Empfänger kurzzeitig nicht erreichbar, wird die Zustellung **automatisch erneut versucht**.
- Schlägt die Zustellung dauerhaft fehl, ist meist die Adresse falsch oder das System des Partners nicht erreichbar. Geben Sie dem Partner in diesem Fall Bescheid. Mit den Angaben aus dem Protokoll kann er den Fehler schnell finden.

### 5.6 Welche Ereignisse gibt es?

Im Portal wählen Sie die Ereignisse über ihre technischen Namen aus. Diese Übersicht hilft bei der Zuordnung:

| Bereich                    | Was löst eine Nachricht aus?                                                                                                                               | Technischer Name im Portal                                 |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **Reservierungen**         | Neue Reservierung angelegt                                                                                                                                 | `reservation.created`                                      |
|                            | Status geändert, z. B. auf *Im Haus*, *Abgereist*, *Storniert* oder *No-Show*                                                                              | `reservation.statusChanged`                                |
|                            | Aufenthalt geändert: An- oder Abreisedatum, An- oder Abreisezeit, Zimmer, Zimmertyp, Tarif oder Personenzahl                                               | `reservation.stayChanged`                                  |
|                            | Gast hat den Online-Check-in abgeschlossen und das Meldeblatt unterschrieben (Gästeportal oder Kiosk)                                                      | `reservation.preCheckInCompleted`                          |
| **Housekeeping**           | Zimmerstatus geändert                                                                                                                                      | `housekeeping.statusChanged`                               |
| **Gäste**                  | Gästeprofil angelegt / geändert / gelöscht                                                                                                                 | `guestProfile.created` / `.updated` / `.deleted`           |
| **Preise & Verfügbarkeit** | Tagespreise geändert                                                                                                                                       | `rates.changed`                                            |
|                            | Restriktionen geändert                                                                                                                                     | `restrictions.changed`                                     |
|                            | Verfügbarkeit geändert                                                                                                                                     | `availability.changed`                                     |
| **Zahlungen**              | Zahlungsanforderung erstellt / bezahlt / fehlgeschlagen                                                                                                    | `paymentRequest.created` / `.completed` / `.failed`        |
|                            | Zahlung gebucht / storniert                                                                                                                                | `payment.created` / `.cancelled`                           |
| **Rechnungen**             | Rechnung erstellt / storniert                                                                                                                              | `invoice.created` / `.cancelled`                           |
| **Berichte**               | Bericht fertig erstellt / fehlgeschlagen                                                                                                                   | `report.completed` / `.failed`                             |
| **Stammdaten**             | Zimmertypen, Zimmer, Tarife, Verpflegungsarten, Altersklassen, Zusatzleistungen, Steuern, Buchungsbedingungen und Saisonen: angelegt / geändert / gelöscht | z. B. `room.created`, `ratePlan.updated`, `season.deleted` |
| **Sicherheit**             | API-Schlüssel angelegt / geändert / gelöscht                                                                                                               | `apiKey.created` / `.updated` / `.deleted`                 |
|                            | Benutzer angelegt / gelöscht, Rollen, E-Mail-Adresse oder Passwort geändert                                                                                | z. B. `user.created`, `user.rolesChanged`                  |
| **Test**                   | Klick auf *Testereignis senden*                                                                                                                            | `webhook.test`                                             |

**Gut zu wissen:**

- Im Portal können Sie auch ganze Gruppen auf einmal wählen, z. B. **alle Reservierungs-Ereignisse**.
- Viele kleine Änderungen werden **gebündelt**: Preise, Restriktionen und Verfügbarkeit werden 30 Sekunden lang gesammelt, Änderungen an Gästeprofilen 60 Sekunden lang. Ändern Sie also im Preisraster 50 Felder hintereinander, bekommt der Empfänger nicht 50 Nachrichten, sondern eine.
- Ereignisse zu Benutzern und API-Schlüsseln betreffen Ihr gesamtes Konto. Haben Sie mehrere Hotels, bekommen die Empfänger jedes dieser Hotels die Nachricht.

### 5.7 Datenschutz: Was steht in einer Nachricht?

Eine Webhook-Nachricht sagt nur, **was** passiert ist und **welcher** Datensatz betroffen ist – zum Beispiel die Nummer der Reservierung und welche Felder sich geändert haben.

**Nie enthalten sind:**

- E-Mail-Adressen von Gästen
- Türcodes, PINs oder Schlüsselkarten-Daten
- Ausweis- und Passdaten
- Passwörter und API-Schlüssel
- Kartendaten und andere Zahlungsdaten
- interne Notizen

Die Details holt sich das empfangende System bei Bedarf über die API – und nur, soweit sein API-Schlüssel es erlaubt.

### 5.8 Hinweise auf der Webhook-Seite

| Hinweis                                                                                      | Bedeutung                                                                                                                                                                                                                                                        |
| -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| *„Webhooks sind für dieses Hotel nicht verfügbar (benötigt die Lizenzen API und Webhooks).“* | Ihrem Hotel fehlt ein Zusatzmodul. Wenden Sie sich an unser Team.                                                                                                                                                                                                |
| *„Webhooks sind derzeit systemweit abgeschaltet – es werden keine Ereignisse versendet.“*    | Der Versand ist von unserer Seite vorübergehend angehalten. Ihre Einstellungen im Portal bleiben erhalten. Ereignisse aus dieser Zeit werden **nicht nachgeliefert** – Ihr Partner sollte nach dem Wiedereinschalten seine Daten einmal über die API abgleichen. |
| *„Der Webhook-Dienst ist in dieser Umgebung nicht eingerichtet.“*                            | Erscheint z. B. in Test-Systemen. Wenden Sie sich an unseren Support, falls Sie das in Ihrem Live-System sehen.                                                                                                                                                  |

***

## 6. Sicherheits-Checkliste

- [ ] Für jeden Partner und jeden Zweck einen **eigenen** API-Schlüssel.
- [ ] Nur die **Berechtigungen**, die wirklich gebraucht werden – wenn möglich nur Lese-Rechte.
- [ ] **Erlaubte IP-Adressen** eingetragen, wenn der Partner feste Adressen hat.
- [ ] Für befristete Projekte ein **Ablaufdatum** gesetzt.
- [ ] Schlüssel und Signatur-Schlüssel **nie** unverschlüsselt per E-Mail oder Chat verschickt.
- [ ] Die Schlüsselliste **regelmäßig geprüft** (z. B. vierteljährlich): Wird jeder Schlüssel noch gebraucht? Passt *Zuletzt verwendet*?
- [ ] Bei Ende einer Zusammenarbeit den Schlüssel **sofort widerrufen** und den Webhook-Empfänger im Portal entfernen.

***

## 7. Häufige Fragen

**Kann ich einen API-Schlüssel später noch einmal anzeigen lassen?**
Nein. Der vollständige Schlüssel ist nur direkt nach dem Erstellen sichtbar. Erstellen Sie bei Bedarf einen neuen und widerrufen Sie den alten.

**Was ist der Unterschied zwischen „deaktivieren“ und „widerrufen“?**
*Deaktivieren* (über *Bearbeiten → Aktiv*) ist wie eine vorübergehend gesperrte Schlüsselkarte – Sie können sie wieder einschalten. *Widerrufen* (über das **×**) macht den Schlüssel endgültig ungültig.

**Warum wurde mein Schlüssel automatisch deaktiviert?**
Er wurde 90 Tage lang nicht verwendet. Sie können ihn über *Bearbeiten* wieder einschalten.

**Gilt ein Schlüssel für alle meine Hotels?**
API-Schlüssel gehören zu Ihrem Konto. Haben Sie mehrere Hotels in einem Konto, erscheint derselbe Schlüssel in allen diesen Hotels in der Liste. Welches Hotel ein Programm anspricht, bestimmt die REST-Basis-URL des jeweiligen Hotels.

**Ein Schlüssel beginnt mit `shms_test_` statt `shms_live_` – was heißt das?**
Er stammt aus einem Test-System und funktioniert nicht in Ihrem Live-Hotel.

**Mein Partner meldet, dass er zu viele Anfragen schickt und abgewiesen wird.**
Pro Schlüssel gibt es eine Obergrenze an Anfragen pro Minute, damit das System für alle schnell bleibt. Die Einzelheiten stehen in der technischen Dokumentation – Ihr Partner kann seine Abfragen entsprechend anpassen oder Webhooks nutzen, statt ständig nachzufragen.

**Kostet die Nutzung von API und Webhooks extra?**
Beide sind Zusatzmodule. Informationen zu Preisen erhalten Sie von unserem Vertriebsteam.

**Kann ich die Webhook-Nachrichten selbst lesen?**
Im Zustellprotokoll des Portals sehen Sie, welche Nachrichten wann an welchen Empfänger gegangen sind. Für die Auswertung der Inhalte ist das empfangende System zuständig.

***

## 8. Begriffe kurz erklärt

| Begriff                  | Erklärung                                                                                            |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| **API**                  | Programmierschnittstelle. Über sie tauschen Programme automatisch Daten mit Ihrer Hotelsoftware aus. |
| **API-Schlüssel**        | Geheimer Zugangscode für ein Programm, vergleichbar mit einer Schlüsselkarte.                        |
| **Berechtigung (Scope)** | Legt fest, was ein API-Schlüssel darf, z. B. *Reservierungen lesen*.                                 |
| **REST-Basis-URL**       | Die Internet-Adresse, unter der Programme Ihr Hotel über die API erreichen.                          |
| **IP-Adresse**           | Die „Hausnummer“ eines Computers im Internet.                                                        |
| **Webhook**              | Automatische Benachrichtigung an ein anderes System, sobald etwas passiert.                          |
| **Ereignis**             | Etwas, das passiert und eine Webhook-Nachricht auslöst, z. B. *Reservierung angelegt*.               |
| **Empfänger**            | Das System, an das Webhook-Nachrichten gehen.                                                        |
| **Signatur-Schlüssel**   | Damit prüft der Empfänger, dass eine Nachricht wirklich von uns kommt.                               |
| **Webhook-Portal**       | Die Verwaltungsoberfläche für Empfänger, Ereignisse und das Zustellprotokoll.                        |
| **Zustellprotokoll**     | Liste der verschickten Nachrichten der letzten 14 Tage mit Zustellstatus.                            |
| **MCP**                  | Ein Standard, über den KI-Assistenten wie Claude mit Ihrer Hotelsoftware verbunden werden.           |
| **β-Version**            | Die Funktion ist neu, voll nutzbar und wird noch weiterentwickelt.                                   |

