Webhooks, SCIM & Pairing

v1.1.x · aktualisiert 2026-07-05

Diese Seite behandelt die verbleibenden Protokolloberflächen: Gerätekopplung, Unternehmen Authentifizierungsföderation (SAML / SCIM / OAuth), die freiwillige Teilnahme MCP-Server und A2A Endpunkte, Medien übertragen, und die Verbinde-RPC Dienste. Einige davon sind standardmäßig deaktiviert und müssen ausdrücklich aktiviert werden.

Geräte koppeln

Mobile- und Desktop-Clients verbinden sich mit einer Instanz über einen kurzen Pairing-Austausch (die iOS/macOS-App verwendet nur QR-Pairing).

Methode & Pfad	Zweck
`POST /v1/pairing/redeem`	Ein Paarungscode einlösen und das Gerät bereitstellen
`POST /v1/pairing/device/validate`	Ein bereits gekoppeltes Gerät validieren

curl https://your-aihummer.example/v1/pairing/redeem \
  -H "Content-Type: application/json" \
  -d '{ "code": "ABCD-EFGH" }'

Authentifizierungsföderation

AiHummer integriert sich mit Unternehmens-Identitätsanbietern sowohl für die Anmeldung als auch für die Benutzerbereitstellung.

SAML

Methode & Pfad	Zweck
`GET /saml/metadata`	Dienstanbieter-Metadaten für Ihren IdP
`POST /saml/acs`	Assertion Consumer Service (SAML-Antwort)
`GET /saml/login`	SAML-Anmeldung starten

SCIM-Bereitstellung

Das System für bereichsübergreifendes Identitätsmanagement (SCIM 2.0) ermöglicht es Ihrem IdP, Benutzer automatisch zu erstellen und zu verwalten.

Methode & Pfad	Zweck
`.../scim/v2/Users`	Benutzer auflisten / erstellen
`.../scim/v2/Users/{id}`	Einen Benutzer lesen / aktualisieren / löschen

Die SCIM-Endpunkte authentifizieren sich mit einem SCIM-Bearer-Token pro Mandant, ausgestellt (und gedreht/widerrufen) bei POST /v1/admin/scim/token; der IdP sendet es in einem Authorization: Bearer Header. Das Token wird einmalig bei der Ausgabe angezeigt.

OAuth-Token

Methode & Pfad	Zweck
`POST /v1/oauth/token`	OAuth-Token-Endpunkt

MCP-Server (nach außen veröffentlichen)

AiHummer kann seine eigenen Werkzeuge an MCP-Kunden veröffentlichen, indem es als ein MCP-Server. Dies ist zustimmen und deaktiviert, es sei denn, Sie stellen ein AIHUMMER_MCP_PUBLISH=1.

Methode & Pfad	Zweck
`POST /v1/mcp`	MCP-Server-Endpunkt (erfordert `AIHUMMER_MCP_PUBLISH=1`)

[!WARNING] AIHUMMER_MCP_PUBLISH=1 allein genügt nicht. Es öffnet die Adresse, aber die Exportliste ist leer: tools/list liefert ein leeres Array und jeder Aufruf wird abgelehnt. Tragen Sie die gewünschten Werkzeuge mit exakten Namen, durch Komma getrennt, in AIHUMMER_MCP_EXPORT_TOOLS ein — Muster und * werden nicht unterstützt. Nach außen dürfen nur lesende Werkzeuge gehen: http_request, web_fetch, browser, code_exec und filesystem_read werden nie exportiert, auch wenn Sie sie nennen.

Beide Einstellungen setzen Sie unter Verwaltung → Einstellungen oder mit aihummer settings set, nicht in gateway.env — für diese Schlüssel wird die Umgebung ignoriert. AIHUMMER_MCP_PUBLISH akzeptiert genau 1: true oder on lassen die Adresse geschlossen. Änderungen greifen nach einem Neustart des Gateways.

Der Client muss einen API-Schlüssel mit dem Bereich mcp im Header Authorization: Bearer … senden; ohne ihn lautet die Antwort 401.

[!NOTE] Das Veröffentlichen von Werkzeugen nach außen unterscheidet sich vom Verwenden eines MCP-Servers als Zero-Code-Integration. Dieser Endpunkt dient dazu, anderen MCP-Clients den Aufruf zu ermöglichen KiHummer.

A2A (Agent-zu-Agent)

AiHummer kann eine A2A-Oberfläche bereitstellen, sodass andere Agenten sie entdecken und Nachrichten senden können. Dies ist auch zustimmen über AIHUMMER_A2A_PUBLISH=1.

Methode & Pfad	Zweck
`GET /.well-known/agent.json`	A2A-Agentenkarte / Entdeckungsdokument
`POST /a2a/message`	Empfange eine A2A-Nachricht (erfordert `AIHUMMER_A2A_PUBLISH=1`)

Medien

Große Medien (Audio, Bilder, Dateien) werden über dedizierte Endpunkte hochgeladen und abgerufen, anstatt in JSON-Body eingebettet zu werden.

Methode & Pfad	Zweck
`PUT /v1/media/{id}/content`	Laden Sie die Bytes für ein Medienobjekt hoch
`GET /v1/files/{id}`	Eine gespeicherte Datei herunterladen

[!TIP] Set AIHUMMER_BLOB_DIR um den Medien-/Dateidienst zu aktivieren, und AIHUMMER_MEDIA_TOKEN_SECRET damit signierte Download-URLs gültig bleiben über startet neu.

Connect-RPC-Dienste

Für getippte, Streaming-Clients stellt AiHummer ebenfalls bereit Verbinde-RPC Dienste über HTTP (Server-Streaming wird unterstützt):

Service	Bereich
`aihummer.health.v1`	Gesundheitschecks
`aihummer.event.v1`	Ereignisstrom
`aihummer.conversation.v1`	Gespräche
`aihummer.push.v1`	Push-Benachrichtigung
`aihummer.media.v1`	Medienübertragung
`aihummer.turn.v1`	Ausführung des Zuges

Wohin als Nächstes

Nachrichten in AiHummer schieben: Eingehende & Integrationsauslöser.
Schalten Sie diese Oberflächen und mehr um: Umgebungsvariablen.
Betreiben Sie die Instanz: CLI-Referenz.