AthausDoku

MCP Events: Webhooks für Anfrage, Termin und Vorschlag

MCP Events als Webhook. Eine verbundene App bekommt Bescheid, wenn eine Anfrage eingeht, ein Termin gebucht wird oder ein Vorschlag wartet.

Zuletzt aktualisiert:

Athaus unterstützt MCP Events nach dem Entwurf "Triggers & Events", zugestellt per Webhook: eine App abonniert ein Ereignis, Athaus schickt bei jedem Eintreten eine signierte Nachricht. Heute nutzt das ChatGPT; Claude abonniert keine Events. Jeder der zwei Server hat eigene Ereignisse (Liste unten, für Athaus für Anbieter und Athaus Immobiliensuche), und ein Abo gehört zum Server seiner Verbindung.

Ablauf

  1. events/list nennt die Ereignisse des Servers mit Zustellart (webhook), Filter-Schema (inputSchema) und Daten-Schema (payloadSchema).

  2. 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 ist https mit öffentlichen IP-Adressen, ohne Umleitung, höchstens 2048 Zeichen; das Geheimnis ist whsec_ plus Base64 aus 24 bis 64 Bytes; Kennungen im Filter müssen zu deinem Büro gehören.

  3. Vor dem ersten Abo schickt Athaus { "type": "verification", "challenge": "..." }. Antworte innerhalb von 10 Sekunden mit 2xx und { "challenge": "..." }.

  4. Ein Abo gilt 10 Minuten bis 24 Stunden (ohne Angabe 24); die Antwort nennt refreshBefore. Dasselbe Abo noch einmal abonniert, verlängert es. Ein neues Geheimnis ersetzt das alte, das 15 Minuten mitsigniert. events/unsubscribe beendet es. Höchstens 50 Abos je Person und App.

Eine Zustellung

POST /hook HTTP/1.1
webhook-id: evt_6f1c...
webhook-timestamp: 1790000000
webhook-signature: v1,<base64>

{ "eventId": "evt_6f1c...", "name": "inquiry.received", "timestamp": "...", "data": { ... }, "cursor": null }
  • Signatur nach Standard Webhooks: HMAC-SHA256 über webhook-id.webhook-timestamp.rumpf, Base64, mit v1, davor (bei einem Wechsel zwei). Die webhook-id bleibt bei jedem Versuch gleich: daran erkennst du eine Wiederholung.
  • Daten enthalten nur Kennungen und einen kurzen Satz (satz); den Inhalt holt die App mit den Werkzeugen, etwa get_inquiry.
  • Zustellung: 10 Sekunden und höchstens 256 KiB je Versuch, vier Versuche (sofort, nach etwa 30 Sekunden, 2 und 8 Minuten). 2xx gilt als zugestellt, 410 und 413 werden nicht wiederholt.
  • Vor jedem Versuch prüft Athaus Zustimmung, Recht und Mitgliedschaft; fehlt eines, ist das Abo entzogen.

Fehler

CodeBedeutung
-32602Parameter falsch (data: delivery.url:<grund> oder delivery.secret)
-32011Das Ereignis gibt es nicht
-32012Nicht erlaubt; data.reason: authentication_required, access_closed, oauth_connection_required (ein Schlüssel), insufficient_scope, arguments_not_in_account, ended_by_user
-32013Zu viele Abos (höchstens 50)
-32015Die Bestätigung der Adresse ist gescheitert

In der App

Unter Einstellungen, MCP steht je App, welche Ereignisse sie abonniert hat. Beenden stoppt ein Abo (die nächste Verlängerung bekommt ended_by_user), Trennen alle Abos der Verbindung.

Athaus für Anbieter

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

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

Weiter lesen

Auf dieser Seite