AthausDocs

MCP Events: webhooks for enquiries, viewings and suggestions

MCP Events as webhooks. A connected app is notified when an enquiry comes in, a viewing is booked or a suggestion is waiting.

Last updated:

Athaus supports MCP Events following the "Triggers & Events" draft, delivered by webhook: an app subscribes to an event, and Athaus sends a signed message each time it happens. Today ChatGPT uses this; Claude does not subscribe to events. Each of the two servers has its own events (list below, for Athaus für Anbieter and Athaus Immobiliensuche), and a subscription belongs to the server of its connection.

How it works

  1. events/list names the events of the server with delivery mode (webhook), filter schema (inputSchema) and data schema (payloadSchema).

  2. events/subscribe needs an OAuth connection with the event's right; a key cannot subscribe.

    {
      "name": "inquiry.received",
      "arguments": { "objekt_id": "0f6b9a3e-2c11-4d5e-9a77-4b1d2e3f4a5b" },
      "delivery": { "mode": "webhook", "url": "https://example.com/hook", "secret": "whsec_..." }
    }

    The address is https with public IP addresses, without redirects, at most 2048 characters; the secret is whsec_ plus Base64 of 24 to 64 bytes; IDs in the filter must belong to your office.

  3. Before the first subscription Athaus sends { "type": "verification", "challenge": "..." }. Answer within 10 seconds with 2xx and { "challenge": "..." }.

  4. A subscription lasts 10 minutes to 24 hours (24 if not specified); the response gives refreshBefore. Subscribing to the same subscription again renews it. A new secret replaces the old one, which keeps signing for 15 minutes. events/unsubscribe ends it. At most 50 subscriptions per person and app.

A delivery

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 }
  • Signature per Standard Webhooks: HMAC-SHA256 over webhook-id.webhook-timestamp.body, Base64, prefixed with v1, (two during a rotation). The webhook-id stays the same on every attempt: that is how you spot a retry.
  • Data contains only IDs and a short sentence (satz); the app fetches the content with the tools, such as get_inquiry.
  • Delivery: 10 seconds and at most 256 KiB per attempt, four attempts (immediately, after about 30 seconds, 2 and 8 minutes). 2xx counts as delivered; 410 and 413 are not retried.
  • Before each attempt Athaus checks consent, right and membership; if one is missing, the subscription is revoked.

Errors

CodeMeaning
-32602Wrong parameters (data: delivery.url:<reason> or delivery.secret)
-32011The event does not exist
-32012Not allowed; data.reason: authentication_required, access_closed, oauth_connection_required (a key), insufficient_scope, arguments_not_in_account, ended_by_user
-32013Too many subscriptions (at most 50)
-32015Verifying the address failed

In the app

Under Settings, MCP each app shows the events it has subscribed to. Unsubscribe stops a subscription (the next renewal gets ended_by_user), Disconnect ends all subscriptions of the connection.

Athaus für Anbieter

inquiry.received

A new enquiry about a property in your portfolio, through Athaus, a portal or email. Where it came from is in quelle. Requires the right lesen.

  • Filters: objekt_id
  • Fields in data: anfrage_id, objekt_id, quelle, satz

message.received

An enquirer has written again in an existing enquiry. Requires the right lesen.

  • Filters: objekt_id, anfrage_id
  • Fields in data: anfrage_id, objekt_id, nachricht_id, satz

viewing.booked

An enquirer has booked a slot at a viewing or moved to another one. Requires the right lesen.

  • Filters: objekt_id
  • Fields in data: termin_id, anfrage_id, objekt_id, beginn, umgebucht, satz

viewing.cancelled

An enquirer has given up their slot at a viewing. The viewing itself may stay. Requires the right lesen.

  • Filters: objekt_id
  • Fields in data: termin_id, anfrage_id, objekt_id, beginn, satz

proposal.pending

The Athaus agent has prepared something that waits for a yes: a draft reply, a rejection, a change to a property. Requires the right lesen.

  • Filters: objekt_id, anfrage_id
  • Fields in data: vorschlag_id, vorschlag_art, geht_hinaus, anfrage_id, objekt_id, satz

file.processed

A document on a property has been read, such as a brochure or an energy certificate. What is now on the property or waits as a suggestion, you read with get_property. Requires the right lesen.

  • Filters: objekt_id
  • Fields in data: objekt_id, datei_id, sorte, angaben, satz

viewing.upcoming

A viewing with guests is coming up: about a day and about an hour before. Requires the right lesen.

  • Filters: objekt_id
  • Fields in data: termin_id, objekt_id, beginn, fenster, satz

Athaus Immobiliensuche

matches.new

Your search briefs have new matches, once per run and order. Requires the right suchen.

  • Filters: saved_search_id
  • Fields in data: saved_search_id, count, satz

reply.received

A provider has replied to your enquiry, with a message or a rejection. Requires the right suchen.

  • Filters: inquiry_id
  • Fields in data: inquiry_id, listing_id, satz

viewing.changed

The provider has moved or cancelled a booked viewing. For a moved one, the new start is in start. Requires the right suchen.

  • Filters: inquiry_id
  • Fields in data: inquiry_id, listing_id, change, start, satz

Keep reading

On this page