# Webhooks und adlass miovea meldet Ereignisse einer Organisation an eigene Endpunkte und lässt sich als Werkzeugkasten in [adlass](https://adlass.io) einbinden. Gesundheitsdaten bleiben dabei in miovea: Ereignisse enthalten nur IDs und Status, Dokumente laufen über vorsignierte URLs direkt zwischen Agent und Speicher. ## Ausgehende Webhooks - Verwalten per Operation (`webhooks.endpoints.create`, `.update`, `.delete`, `.rotate_secret`, `.test`) oder in der App unter Einstellungen > KI-Zugriff > Webhooks; nur Admins. `webhooks.events.list` nennt die Ereignistypen. - Signatur nach [Standard Webhooks](https://www.standardwebhooks.com/): Header `webhook-id`, `webhook-timestamp`, `webhook-signature` (`v1,` über `{id}.{timestamp}.{body}`, Schlüssel = base64-dekodierte Bytes hinter `whsec_`). Bei einer Secret-Rotation stehen 24 Stunden lang zwei Signaturen im Header. - Body `{ type, timestamp, data }`; `data` enthält `org_id`, die betroffene Objekt-ID sowie `preinquiry_id`, `customer_id`, `customer_external_ref`, `preinquiry_external_ref`, wo vorhanden. Keine Namen, keine Gesundheitsangaben, keine Dateinamen. - Ereignisse: `questionnaire.submitted`, `customer_link.document_uploaded`, `document.created`, `vote.received`, `inbox.message.matched`, `dispatch.delivered`, `dispatch.failed`, `preinquiry.status_changed`, `webhook.test`. - Zustellung mindestens einmal, 2xx innerhalb 10 Sekunden erwartet; Wiederholungen mit Backoff (höchstens 10 Versuche innerhalb von 72 Stunden, `Retry-After` innerhalb dieser Grenzen beachtet), danach wird der Endpunkt deaktiviert und der Vorgang steht im Verlauf. Anlegen, Ändern und Testen von Endpunkten unterliegen der Agenten-Richtlinie `allow_external`. `410 Gone` deaktiviert sofort. Ziele müssen `https` und öffentlich erreichbar sein; private, lokale und Metadaten-Adressen sind gesperrt. - Details, Prüfcode und Fehlerfälle: Guide `webhooks` (`read_guide("webhooks")`, `GET /api/v1/operations/guides/webhooks`). ## Externe Referenzen `external_ref` an Kunde und Vorgang verbindet miovea-Objekte mit Datensätzen eines anderen Systems: Format `::` (z. B. `adlass:contact:7f3c…`), höchstens 200 Zeichen, je Organisation eindeutig. `customers.create/update` und `preinquiries.create/update` nehmen sie an, `customers.list` und `preinquiries.list` filtern danach; eine Kollision antwortet mit `conflict` und nennt `details.customer_id` bzw. `details.preinquiry_id`. Trifft `customers.create` einen bestehenden Kunden ohne Referenz, übernimmt dieser die mitgegebene; genauso ein offener Vorgang bei `preinquiries.create`. ## Agenten-Modus der Organisation Unter Einstellungen > KI-Zugriff wählt ein Admin den KI-Modus: - **Plattform** (Standard): miovea liest Dokumente aus, sortiert den Posteingang vor, liest Voten aus Antworten, prüft Fragebögen und formuliert Freitexte. Verhalten wie bisher. - **Agent**: miovea ruft kein Modell auf; nur die Texterkennung (OCR) bleibt. Die inhaltliche Arbeit macht der angebundene Agent. Operationen mit Modellaufruf antworten mit `ai_processing_disabled`; der Hinweis nennt den Guide für den eigenen Weg. `get_context` bzw. `GET /api/v1/operations/context` zeigen `ai_processing_mode`. ## Anbindung über adlass adlass verbindet miovea pro Nutzer über OAuth (Authorization Code + PKCE gegen Clerk, Scope `user:org:read`, Auswahl der Organisation im Consent-Screen) oder über einen API-Key der Organisation. Der lokale Agent des Maklers ruft miovea-Operationen über den adlass-Provider auf: Lesen per `GET /api/v1/operations/{key}/invoke?…`, Schreiben per `POST …/invoke` mit `idempotency_key`; Bestätigungen (`confirmation_required`) zeigt der Agent dem Nutzer und wiederholt mit `confirm: true`. Ereignisse erreichen adlass über einen Webhook-Endpunkt, den adlass beim Verbinden anlegt. Im Verlauf stehen diese Aufrufe als „per KI-Agent · adlass“. Einstieg: `GET /api/v1/operations/guides/integration_adlass`.