API-Schlüssel und Webhooks

Unter Schnittstellen legen Sie API-Schlüssel an, mit denen eigene Systeme die Integrationsschnittstelle aufrufen, und Webhooks, über die XICBOT Ereignisse an eine Adresse Ihres Systems meldet. Die Seite liegt unter https://app.xicbot.de/schnittstellen, im Menü in der Gruppe Verwaltung. Grundbegriffe der Schnittstelle stehen unter API-Grundlagen.

Wer die Seite sieht und nutzt

Der Menüpunkt Schnittstellen erscheint ab der Rolle Verwaltung; die Rolle Inhaber schließt sie ein. Mit Lesen oder Bearbeiten fehlt der Punkt, und die Schnittstelle antwortet mit 403 und dem Kennzeichen role_too_low. Wer die Seite trotzdem aufruft, sieht nur „Das darf, wer mindestens die Rolle Verwaltung hat.“, ohne Formulare und Listen. Die Rollen beschreibt Team und Rollen.

Schlüssel und Webhooks gehören zu einer Funktion, die nur das Paket Individuell enthält. Fehlt sie, zeigt die Seite statt der Formulare den Satz „Der Tarif … enthält diese Funktion nicht. Die Übersicht steht unter Abrechnung.“ mit dem Namen Ihres Tarifs an Stelle der Auslassungspunkte und den Link Zur Abrechnung; ist kein Tarifname bekannt, lautet der Satz „Der gebuchte Tarif deckt das nicht ab. Die Übersicht steht unter Abrechnung.“ Schlüssel und Webhooks aus der Zeit vor einem Tarifwechsel stehen weiter darunter, und der Satz „Vorhandene Schlüssel und Webhooks bleiben hier sichtbar: Schlüssel lassen sich zurückziehen, Webhooks löschen. Solange der Tarif die Funktion nicht enthält, weist die Schnittstelle diese Schlüssel ab, und Webhooks erhalten keine Zustellungen.“ kommt hinzu. Zurückziehen, Zustellungen und Löschen bleiben, Probe senden, Abschalten und Einschalten fehlen. Über die Schnittstelle antworten Anlegen, Ändern und Probe mit 402 und plan_feature_missing, ebenso jeder Aufruf mit einem solchen Schlüssel; Liste, Zustellprotokoll, Zurückziehen und Löschen gehen auch ohne die Funktion. Enthält das Paket die Funktion wieder, arbeiten dieselben Schlüssel und Webhooks weiter; Ereignisse aus der Zwischenzeit werden nicht nachgeliefert. Welche Pakete die Funktion enthalten, zeigen Preise und Pakete und Kontingente.

• Einen Schlüssel mit dem Bereich Gespräche lesen legt nur die Rolle Inhaber an, weil dieser Bereich die Nachrichten im Klartext liefert. Für andere Rollen ist das Kästchen gesperrt. Die Schnittstelle weist einen solchen Versuch mit 403, role_too_low und "required": "owner" ab, die App meldet „Das darf nur der Inhaber des Kontos.“
• Schlüssel anlegen, Webhook anlegen und Probe senden zählen gemeinsam gegen eine Grenze von 10 Aufrufen pro Minute und angemeldeter Person. Darüber antwortet die Schnittstelle mit 429, die App zeigt „Zu viele Versuche. Bitte warten Sie einen Moment.“
• Ist das Konto nicht aktiv, antworten die Aufrufe dieser Seite mit 403 und einem Kennzeichen der Form tenant_<status>; das Feld message lautet „Das Konto ist derzeit nicht aktiv.“ Die App zeigt „Dieses Konto ist gesperrt. Bitte schreiben Sie an mail@xicbot.de.“

API-Schlüssel

Ein API-Schlüssel beginnt mit xbot_, gefolgt von 48 zufälligen Zeichen. „Ein Schlüssel wird genau einmal im Klartext angezeigt. Gespeichert wird nur sein Abdruck.“ Neben dem SHA-256-Abdruck bleiben die ersten 12 Zeichen als Kennung stehen. Ein verlorener Schlüssel lässt sich darum nicht wiederherstellen, nur ersetzen.

Schlüssel anlegen

1. 1

   Schritt 1

   Name vergeben

   Unter Name tragen Sie eine Bezeichnung ein, an der Sie den Schlüssel später erkennen, etwa das System, das ihn nutzt. Höchstens 80 Zeichen.

2. 2

   Schritt 2

   Grenze und Ablauf festlegen

   Anfragen pro Minute begrenzt, wie oft dieser Schlüssel pro Minute aufrufen darf, vorbelegt mit 120. Läuft ab in Tagen setzt ein Ablaufdatum, gerechnet ab dem Anlegen; „Leer bedeutet ohne Ablauf.“

3. 3

   Schritt 3

   Bereiche wählen

   Unter Bereiche kreuzen Sie mindestens einen Bereich an. Ohne Name oder ohne Bereich bleibt Neuen Schlüssel anlegen gesperrt.

4. 4

   Schritt 4

   Schlüssel kopieren

   Es erscheint die Karte Ihr neuer Schlüssel mit dem Hinweis „Jetzt kopieren. Nach dem Schließen ist er nicht wieder abrufbar.“ Schlüssel kopieren legt ihn in die Zwischenablage, danach steht Schlüssel kopiert; ist die Zwischenablage nicht erreichbar, erscheint Die Zwischenablage ist hier nicht verfügbar. Markieren Sie den Wert und kopieren Sie ihn von Hand. Schließen nimmt ihn aus der Ansicht. Name, Bereiche und Ablauf werden geleert, die Grenze bleibt stehen.

Bereiche

Ein Schlüssel ruft nur die Routen auf, deren Bereich er trägt; „Schreiben ist ein eigener Bereich. Ohne ihn liest ein Schlüssel nur.“ GET /api/v1/integration/status braucht keinen Bereich. Welche Routen jeder Bereich öffnet und wie die Schnittstelle einen fehlenden Bereich ablehnt, steht unter API-Anmeldung.

Was die einzelnen Routen liefern, beschreibt API-Integration.

Die Schlüsselliste

Die Liste zeigt die Schlüssel des Kontos, neueste zuerst. Solange keiner angelegt ist, steht dort „Noch kein Schlüssel angelegt.“

Schlüssel zurückziehen

Zurückziehen fragt nach: „Schlüssel zurückziehen? Anfragen mit diesem Schlüssel werden danach abgewiesen.“ Erst ein zweites Zurückziehen wirkt, Abbrechen lässt den Schlüssel unverändert. Der Schlüssel bleibt danach mit dem Status zurückgezogen in der Liste und lässt sich nicht wieder gültig machen; Anfragen mit ihm erhalten 401 und invalid_key. Auch abgelaufene Schlüssel lassen sich zurückziehen.

Schlüssel verwenden

Den Schlüssel senden Sie im Kopf X-Api-Key an Routen unter /api/v1/integration. Ein Schlüssel in der Adresse, also ?api_key= oder ?key=, wird mit 400 und key_in_url abgewiesen. Einzelheiten zur Anmeldung stehen unter API-Anmeldung, zu den Grenzen unter API-Grenzen.

curl -s https://app.xicbot.de/api/v1/integration/status \
  -H "X-Api-Key: $XICBOT_API_KEY"

Wie die Schnittstelle einen Schlüssel der Reihe nach prüft und welche Antwort zu welcher Stufe gehört, steht unter API-Anmeldung, die Minuten- und Tagesdeckel unter Paketsperren und Drosseln.

Webhooks

Ein Webhook ist eine Zieladresse in Ihrem System, an die XICBOT bei gewählten Ereignissen eine signierte POST-Anfrage sendet. „Jede Sendung trägt eine Unterschrift im Kopf X-XICBOT-Signature. Fehlgeschlagene Sendungen werden wiederholt.“ Solange keiner eingerichtet ist, steht dort „Noch kein Webhook eingerichtet.“

Webhook anlegen

1. 1

   Schritt 1

   Zieladresse eintragen

   Unter Zieladresse tragen Sie die Adresse Ihres Empfängers ein, etwa https://example.com/xicbot-webhook, höchstens 2048 Zeichen. Zugelassen sind http und https; wir empfehlen https. Welche Ziele abgewiesen werden, steht unter Zulässige Zieladressen.

2. 2

   Schritt 2

   Ereignisse wählen

   Unter Ereignisse kreuzen Sie mindestens eines der zehn Ereignisse an. Ohne Adresse oder ohne Ereignis bleibt Webhook anlegen gesperrt.

3. 3

   Schritt 3

   Geheimnis sichern

   Es erscheint die Karte Ihr Signaturgeheimnis mit dem Satz „Damit prüfen Sie die Unterschrift der eingehenden Sendung.“ Das Geheimnis beginnt mit whsec_, gefolgt von 48 Zeichen. Geheimnis kopieren legt es in die Zwischenablage, Schließen nimmt es aus der Ansicht.

Ereignisse

Neben der Beschriftung in der App steht der technische Name, der im Feld event und im Kopf X-XICBOT-Event ankommt. Welche Felder data trägt, hängt vom Ereignis ab; Kennungen kommen als Zeichenkette.

Eine erneut erfasste, gleiche Anfrage oder Terminanfrage löst kein zweites Ereignis aus. Besuchertext in question und reason geht maskiert hinaus: E-Mail-Adressen, Rufnummern, Kontonummern und Anschriften stehen als Platzhalter wie [E-Mail]; maskiert wird vor dem Kürzen. Den Klartext eines Gesprächs gibt nur ein Schlüssel mit dem Bereich conversations heraus, und den legt nur der Inhaber an. Zusätzlich gibt es das Ereignis probe; es entsteht nur über Probe senden, lässt sich nicht abonnieren und trägt in data das Feld note. Zu Gesprächen, Übergaben und Wissen siehe Gespräche, Termine und Vorgänge und Wissensaufbau und Antworten.

Probe und Zustellungen

Jede Webhook-Karte zeigt die Zieladresse, die abonnierten Ereignisse und den Zustand gültig oder abgeschaltet, dahinter Fehler in Folge mit Stand und Grenze, etwa 0 / 20.

• Probe senden stellt sofort eine Sendung mit dem Ereignis probe zu, ohne Wiederholung und auch an einen abgeschalteten Webhook. Darunter erscheint Probe zugestellt mit dem Statuscode Ihres Empfängers oder Probe fehlgeschlagen mit dem Text aus den Zustellgründen, ersatzweise mit dem Statuscode oder der Fehlermeldung der Verbindung. Danach zeigt die Seite die Zustellungen dieses Webhooks. Eine Probe zählt wie jede Zustellung in Fehler in Folge.
• Zustellungen klappt die letzten 50 Zustellungen dieses Webhooks auf, neueste zuerst, mit den Spalten Zeit, Ereignisse, Versuch, Status und Dauer. Unter Status steht bei Erfolg der Statuscode, bei einem Fehlschlag der Text aus den Zustellgründen, ersatzweise der Statuscode oder die Fehlermeldung der Verbindung. Dauer ist in Millisekunden angegeben. Ohne Eintrag steht dort „Noch keine Zustellung.“
• Gespeichert wird je Zustellung ein SHA-256-Abdruck des gesendeten Körpers, nicht der Inhalt. Wiederholungen eines Ereignisses erscheinen als eigene Zeilen mit steigendem Versuch.

Abschalten, einschalten, löschen

Der dritte Knopf der Karte schaltet um: Bei einem laufenden Webhook heißt er Abschalten, bei einem abgeschalteten Einschalten. Ein abgeschalteter Webhook erhält keine Ereignisse, und bereits geplante Wiederholungen entfallen. Beim Einschalten beginnt Fehler in Folge wieder bei 0.

Löschen fragt zuerst nach: Diesen Webhook löschen? Zustellungen an diese Adresse enden sofort, und das Signaturgeheimnis lässt sich nicht wiederherstellen. Darunter steht die Zieladresse, dazu die Knöpfe Abbrechen und Löschen. Erst die Bestätigung entfernt den Webhook samt seinem Zustellprotokoll; ausstehende Zustellungen entfallen. Adresse und Geheimnis lassen sich nicht ändern. Die abonnierten Ereignisse ändern Sie über PUT /api/v1/webhooks/{id}, in der App nicht.

Zustellung und Signatur

Aufbau einer Sendung

Jede Sendung ist ein POST mit einem JSON-Körper aus vier Feldern: event, at (Zeitpunkt des Ereignisses nach ISO 8601, für alle Versuche gleich), tenant (Kennung Ihres Kontos) und data. Umlaute und Schrägstriche stehen unmaskiert im Text.

{
  "event": "lead.created",
  "at": "2026-09-28T10:15:00+00:00",
  "tenant": "<Kontokennung>",
  "data": {
    "id": "<Anfragekennung>",
    "conversation_id": "<Gesprächskennung>"
  }
}

Signatur prüfen

Die Signatur ist ein HMAC-SHA256 über den Zeitstempel t, einen Punkt und den unveränderten Anfragekörper. Als Schlüssel dient das ganze Geheimnis einschließlich whsec_. Prüfen Sie den Rohkörper, wie er ankommt, nicht ein daraus neu erzeugtes JSON: eine andere Feldreihenfolge oder maskierte Umlaute ergeben eine andere Signatur.

• Den Kopf X-XICBOT-Signature an den Kommas trennen und t und v1 lesen.
• t, einen Punkt und den Rohkörper mit dem Geheimnis per HMAC-SHA256 verrechnen und als Hex schreiben.
• Das Ergebnis mit v1 in gleichbleibender Zeit vergleichen, nicht mit einem einfachen Gleichheitsvergleich.
• Das Alter der Sendung über t begrenzen, etwa auf fünf Minuten, damit eine mitgeschnittene Sendung nicht später erneut eingespielt werden kann.
• Innerhalb von 8 Sekunden mit einem Status von 200 bis 299 antworten und aufwendige Arbeit danach erledigen.

import { createHmac, timingSafeEqual } from 'node:crypto';

// Prüft X-XICBOT-Signature gegen den Rohkörper (Buffer oder String).
export function verifySignature(rawBody, header, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(
    String(header ?? '').split(',').map((part) => part.split('=', 2)),
  );
  const t = Number(parts.t);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) {
    return false; // fehlt oder zu alt
  }
  const expected = createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex');
  const given = Buffer.from(String(parts.v1 ?? ''), 'hex');
  const wanted = Buffer.from(expected, 'hex');
  return given.length === wanted.length && timingSafeEqual(given, wanted);
}

<?php
// Rohkörper lesen, nicht $_POST und kein neu erzeugtes JSON
$body = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_XICBOT_SIGNATURE'] ?? '';
parse_str(str_replace(',', '&', $header), $parts);
$t = (int) ($parts['t'] ?? 0);
$expected = hash_hmac('sha256', $t . '.' . $body, getenv('XICBOT_WEBHOOK_SECRET'));
$fresh = abs(time() - $t) <= 300;
if (!$fresh || !hash_equals($expected, (string) ($parts['v1'] ?? ''))) {
    http_response_code(400);
    exit;
}
http_response_code(204);
$event = json_decode($body, true);

Zur Kontrolle: der SHA-256-Abdruck des Rohkörpers entspricht dem Feld content_hash der Zustellung in GET /api/v1/webhooks/{id}/deliveries.

Wiederholung

Ereignisse werden im Hintergrund zugestellt. Als Erfolg gilt eine Antwort mit Status 200 bis 299 innerhalb von 8 Sekunden. Umleitungen mit Status 300 bis 399 werden nicht verfolgt und gelten als Fehlschlag. Nach einem Fehlschlag folgt ein zweiter Versuch nach etwa 30 Sekunden und ein dritter nach etwa 120 Sekunden; scheitert auch er, wird das Ereignis nicht weiter zugestellt. Die Verarbeitung im Hintergrund beschreibt Hintergrundaufträge.

• Jeder Versuch wird neu signiert: t ändert sich, X-XICBOT-Attempt zählt hoch. at und X-XICBOT-Delivery bleiben für alle Versuche eines Ereignisses gleich; eine Wiederholung erkennen Sie darum an X-XICBOT-Delivery. Eine Probe erhält bei jedem Senden eine neue Kennung.
• Ist der Webhook beim Versuch abgeschaltet oder gelöscht oder enthält das Paket die Funktion nicht mehr, entfällt die Zustellung ohne weiteren Versuch und ohne Eintrag im Zustellprotokoll.
• Scheitert die Prüfung der Zieladresse erst beim Versand, etwa weil der Name inzwischen auf eine interne Adresse zeigt, wird der Versuch protokolliert, wiederholt und in Fehler in Folge gezählt wie bei einem Empfänger, der nicht antwortet. Lässt sich das Signaturgeheimnis nicht lesen, wird der Versuch protokolliert und wiederholt, zählt aber nicht in Fehler in Folge.

Zulässige Zieladressen

Die Adresse wird beim Anlegen und vor jedem Versand geprüft. Zugelassen sind http und https. Der Name muss sich auflösen lassen und auf eine öffentliche Adresse zeigen; private und reservierte Bereiche wie 10.0.0.0/8 oder 192.168.0.0/16 werden abgewiesen. Zeigt der Name auf mehrere Adressen, muss jede öffentlich sein; verbunden wird nur mit den geprüften Adressen. Beim Anlegen meldet die App „Diese Adresse ist als Ziel nicht zugelassen.“, die Schnittstelle antwortet mit 422 und einem der Gründe url_unreadable, scheme_not_allowed, name_unresolvable oder target_not_allowed im Feld error.

Gründe fehlgeschlagener Zustellungen

Diese Kennzeichen stehen im Feld reason der Probe und im Feld error des Zustellprotokolls. Die App zeigt dazu folgende Texte:

Verwaltung über die Schnittstelle

Dieselben Vorgänge stehen unter /api/v1 bereit. Angemeldet wird mit der Sitzungsmarke einer Person mit mindestens der Rolle Verwaltung, nicht mit einem API-Schlüssel: ein API-Schlüssel verwaltet weder Schlüssel noch Webhooks. Wie Sie eine Sitzungsmarke erhalten, steht unter API-Anmeldung. Fehler kommen als JSON, in der Regel mit einem Kennzeichen im Feld error; Feldfehler stehen im Feld errors.

Routen für Schlüssel

curl -s https://app.xicbot.de/api/v1/keys \
  -H "Authorization: Bearer <Marke>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Warenwirtschaft", "scopes": ["leads", "leads.write"], "limit_per_min": 60, "expires_in_days": 365}'

Routen für Webhooks

Fehlerantworten

Aufbewahrung und Löschung

• Das Zustellprotokoll wird nach der Frist für Protokolle gelöscht, die für Ihr Konto gilt; steht sie auf 0, entfällt dieses Löschen. Mit einem Webhook geht auch sein Protokoll.
• Zurückgezogene und abgelaufene Schlüssel bleiben in der Liste stehen; ein Löschen einzelner Schlüssel gibt es nicht.
• Der Datenexport des Kontos enthält Schlüssel, Webhooks und Zustellprotokoll, jedoch ohne Schlüsselabdruck und ohne Signaturgeheimnis.
• Beim Löschen des Kontos werden Schlüssel, Webhooks und Zustellprotokoll gelöscht.

Fristen und Export beschreibt Aufbewahrung und Löschung, den Schutz von Zugangsdaten Datensicherheit.

Häufige Fragen