# MCP Events: webhooks for enquiries, viewings and suggestions

Adresse: https://docs.athaus.ai/en/mcp/ereignisse

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

Type: Reference
Last updated: 2026-11-10

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](/en/mcp) has its own events (list below, for [Athaus für Anbieter](#anbieter) and [Athaus Immobiliensuche](#suche)), and a subscription belongs to the server of its connection.

## How it works [#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.

   ```json
   {
     "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 [#a-delivery]

```http
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](/en/mcp/werkzeuge/anbieter), 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 [#fehler]

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

## In the app [#in-the-app]

Under [Settings, MCP](https://app.athaus.ai/einstellungen/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 [#anbieter]

### inquiry.received [#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`](/en/mcp/rechte#lesen).

* Filters: `objekt_id`
* Fields in `data`: `anfrage_id`, `objekt_id`, `quelle`, `satz`

### message.received [#message-received]

An enquirer has written again in an existing enquiry. Requires the right [`lesen`](/en/mcp/rechte#lesen).

* Filters: `objekt_id`, `anfrage_id`
* Fields in `data`: `anfrage_id`, `objekt_id`, `nachricht_id`, `satz`

### viewing.booked [#viewing-booked]

An enquirer has booked a slot at a viewing or moved to another one. Requires the right [`lesen`](/en/mcp/rechte#lesen).

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

### viewing.cancelled [#viewing-cancelled]

An enquirer has given up their slot at a viewing. The viewing itself may stay. Requires the right [`lesen`](/en/mcp/rechte#lesen).

* Filters: `objekt_id`
* Fields in `data`: `termin_id`, `anfrage_id`, `objekt_id`, `beginn`, `satz`

### proposal.pending [#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`](/en/mcp/rechte#lesen).

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

### file.processed [#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`](/en/mcp/rechte#lesen).

* Filters: `objekt_id`
* Fields in `data`: `objekt_id`, `datei_id`, `sorte`, `angaben`, `satz`

### viewing.upcoming [#viewing-upcoming]

A viewing with guests is coming up: about a day and about an hour before. Requires the right [`lesen`](/en/mcp/rechte#lesen).

* Filters: `objekt_id`
* Fields in `data`: `termin_id`, `objekt_id`, `beginn`, `fenster`, `satz`

## Athaus Immobiliensuche [#suche]

### matches.new [#matches-new]

Your search briefs have new matches, once per run and order. Requires the right [`suchen`](/en/mcp/rechte#suchen).

* Filters: `saved_search_id`
* Fields in `data`: `saved_search_id`, `count`, `satz`

### reply.received [#reply-received]

A provider has replied to your enquiry, with a message or a rejection. Requires the right [`suchen`](/en/mcp/rechte#suchen).

* Filters: `inquiry_id`
* Fields in `data`: `inquiry_id`, `listing_id`, `satz`

### viewing.changed [#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`](/en/mcp/rechte#suchen).

* Filters: `inquiry_id`
* Fields in `data`: `inquiry_id`, `listing_id`, `change`, `start`, `satz`
