Events
MCP Events als Webhook. Eine verbundene App bekommt Bescheid, wenn eine Anfrage eingeht, ein Termin gebucht wird oder ein Vorschlag wartet.
Athaus unterstützt MCP Events nach dem Entwurf "Triggers & Events", und davon die Zustellung per Webhook. Eine App abonniert ein Ereignis, Athaus schickt ihr bei jedem Eintreten eine signierte Nachricht. Heute nutzt das ChatGPT; Claude abonniert keine Events über MCP.
Jeder der zwei Server hat seine eigenen Ereignisse, und ein Abo entsteht an dem Server, zu dem die Verbindung gehört. Gebaut sind bisher die Ereignisse von Athaus für Makler; die Liste je Server steht unten, aus dem Vertrag erzeugt.
Ablauf
Ereignisse auflisten
events/list braucht eine Anmeldung, wie jeder Aufruf, und nennt die gebauten Ereignisse des Servers, an dem gefragt wird. Es gibt je Ereignis den Namen, eine Beschreibung, die Zustellart (webhook), das Schema der Filter (inputSchema) und das Schema der Daten (payloadSchema) zurück.
Abonnieren
events/subscribe braucht eine Verbindung über OAuth mit dem Recht des Ereignisses; ein Schlüssel kann nicht abonnieren.
{
"name": "inquiry.received",
"arguments": { "objekt_id": "0f6b9a3e-2c11-4d5e-9a77-4b1d2e3f4a5b" },
"delivery": { "mode": "webhook", "url": "https://example.com/hook", "secret": "whsec_..." }
}- Die Adresse muss
httpssein, jede ihrer IP-Adressen öffentlich, ohne Umleitung, höchstens 2048 Zeichen. - Das Geheimnis hat die Form
whsec_plus Base64 aus 24 bis 64 Bytes. - Die Kennungen im Filter müssen zu deinem Büro gehören.
Die Adresse bestätigen
Vor dem ersten Abo schickt Athaus eine signierte Bestätigung an die Adresse:
{ "type": "verification", "challenge": "..." }Der Empfänger antwortet innerhalb von 10 Sekunden mit 2xx und { "challenge": "..." }. Eine Bestätigung gilt 24 Stunden je Person, App und Adresse.
Verlängern oder beenden
Das Abo gilt zwischen 10 Minuten und 24 Stunden, ohne Angabe 24 Stunden, nie unbegrenzt; die Antwort nennt refreshBefore. Wer dasselbe Abo noch einmal abonniert, verlängert es; seine Kennung bleibt gleich. Ein neues Geheimnis ersetzt das alte, das alte signiert noch 15 Minuten mit. events/unsubscribe mit Name, Filter und Adresse beendet es und antwortet {}. Je Person und App laufen höchstens 50 Abos.
Eine Zustellung
POST /hook HTTP/1.1
content-type: application/json
webhook-id: evt_6f1c...
webhook-timestamp: 1790000000
webhook-signature: v1,<base64>
x-mcp-subscription-id: sub_9a2e...
user-agent: athaus-mcp-events
{ "eventId": "evt_6f1c...", "name": "inquiry.received", "timestamp": "...", "data": { ... }, "cursor": null }- Signatur nach Standard Webhooks: HMAC-SHA256 mit dem Geheimnis über
webhook-id.webhook-timestamp.rumpf, Base64, mitv1,davor. Während eines Wechsels stehen zwei Signaturen mit Leerzeichen getrennt da. webhook-idist die Kennung des Ereignisses und bei jedem Versuch dieselbe: daran erkennt der Empfänger eine Wiederholung.- Daten enthalten nur Kennungen und einen kurzen Satz (
satz), nie den Inhalt einer Nachricht. Den holt die App mit den Werkzeugen, etwaget_inquiry. - Zeit und Größe: 10 Sekunden je Versuch, höchstens 256 KiB.
- Wiederholung: vier Versuche, sofort und nach etwa 30 Sekunden, 2 und 8 Minuten.
2xxgilt als zugestellt.410und413werden nicht wiederholt. - Vor jedem Versuch prüft Athaus Zustimmung, Recht und Mitgliedschaft. Fehlt eines, ist das Abo entzogen.
- Ein Ereignis, das eine App selbst ausgelöst hat, geht nicht an dieselbe App zurück.
Fehler
| Code | Bedeutung |
|---|---|
-32602 | Parameter falsch, mit data wie delivery.url:<grund> oder delivery.secret |
-32011 | Das Ereignis gibt es nicht |
-32012 | Nicht erlaubt; data.reason ist authentication_required, access_closed, oauth_connection_required (ein Schlüssel), insufficient_scope, arguments_not_in_account oder ended_by_user |
-32013 | Zu viele Abos ({ "limit": "subscriptions", "max": 50 }) |
-32014 | Nicht unterstützt: eine andere Zustellart als Webhook, events/poll, events/stream |
-32015 | Die Bestätigung der Adresse ist gescheitert |
-32603 | Events sind auf dem Server nicht eingerichtet (events_not_configured) |
In der App
Unter Einstellungen, MCP-Server steht bei jeder verbundenen App, welche Ereignisse sie abonniert hat. Beenden stoppt ein Abo; die nächste Verlängerung der App bekommt dann ended_by_user. Trennen beendet alle Abos dieser Verbindung.
Athaus für Makler
inquiry.received
Eine neue Anfrage an einem Objekt deines Bestands, über Athaus, ein Portal oder E-Mail. Woher sie kam, steht in quelle. Braucht das Recht lesen.
- Filter:
objekt_id - Felder in
data:anfrage_id,objekt_id,quelle,satz
message.received
Ein Interessent hat in einer bestehenden Anfrage wieder geschrieben. Braucht das Recht lesen.
- Filter:
objekt_id,anfrage_id - Felder in
data:anfrage_id,objekt_id,nachricht_id,satz
viewing.booked
Ein Interessent hat einen Platz an einer Besichtigung gebucht oder ist auf einen anderen Termin umgebucht. Braucht das Recht lesen.
- Filter:
objekt_id - Felder in
data:termin_id,anfrage_id,objekt_id,beginn,umgebucht,satz
viewing.cancelled
Ein Interessent hat seinen Platz an einer Besichtigung abgegeben. Der Termin selbst kann bleiben. Braucht das Recht lesen.
- Filter:
objekt_id - Felder in
data:termin_id,anfrage_id,objekt_id,beginn,satz
proposal.pending
Der Agent von Athaus hat etwas vorbereitet, das auf ein Ja wartet: einen Antwortentwurf, eine Absage, eine Änderung am Objekt. Braucht das Recht lesen.
- Filter:
objekt_id,anfrage_id - Felder in
data:vorschlag_id,vorschlag_art,geht_hinaus,anfrage_id,objekt_id,satz
file.processed
Eine Unterlage an einem Objekt ist ausgelesen, etwa ein Exposé oder ein Energieausweis. Was davon am Objekt steht oder als Vorschlag wartet, liest du mit get_property. Braucht das Recht lesen.
- Filter:
objekt_id - Felder in
data:objekt_id,datei_id,sorte,angaben,satz
viewing.upcoming
Eine Besichtigung mit Gästen steht bevor: etwa einen Tag und etwa eine Stunde vorher. Braucht das Recht lesen.
- Filter:
objekt_id - Felder in
data:termin_id,objekt_id,beginn,fenster,satz
social.received
Ein neuer Kommentar oder eine neue Nachricht in deinen Netzen. Braucht das Recht lesen.
- Filter:
objekt_id - Felder in
data:eingang_id,art,netz,objekt_id,satz
Athaus Immobiliensuche
matches.new
Deine Suchaufträge haben neue Treffer, einmal je Lauf und Auftrag. Braucht das Recht suchen.
- Filter:
saved_search_id - Felder in
data:saved_search_id,count,satz
reply.received
Ein Anbieter hat auf deine Anfrage geantwortet, mit einer Nachricht oder einer Absage. Braucht das Recht suchen.
- Filter:
inquiry_id - Felder in
data:inquiry_id,listing_id,satz
viewing.changed
Der Anbieter hat eine gebuchte Besichtigung verschoben oder abgesagt. Bei einer verschobenen steht der neue Beginn in start. Braucht das Recht suchen.
- Filter:
inquiry_id - Felder in
data:inquiry_id,listing_id,change,start,satz