# REST-API: Webhooks

Adresse: https://docs.athaus.ai/api/v1/webhooks

> Ereignisse an eine Adresse deines Systems: einrichten, die Signatur prüfen, Wiederholungen verstehen, das Secret wechseln.

Typ: Anleitung
Zuletzt aktualisiert: 2026-11-14

Ein Webhook-Endpunkt ist eine Adresse deines Systems, an die Athaus ein Ereignis schickt, sobald es geschieht: eine neue Anfrage, eine gebuchte Besichtigung. Du hörst auf abzufragen. Was ein Endpunkt verpasst hat, holst du über [Ereignisse](/api/v1/ereignisse).

## Einrichten [#einrichten]

```bash
curl https://api.athaus.ai/v1/webhookEndpoints \
  -H "Authorization: Bearer ath_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.org/hooks/athaus",
    "events": ["inquiry.received", "viewing.booked"],
    "description": "CRM-Abgleich"
  }'
```

Die Antwort ist `201` und trägt das Secret, mit dem Athaus signiert:

```json
{
  "object": "webhook_endpoint",
  "id": "0190f3b0-5a71-7c3e-8f12-6d0a9e4b7c21",
  "url": "https://example.org/hooks/athaus",
  "description": "CRM-Abgleich",
  "events": ["inquiry.received", "viewing.booked"],
  "status": "enabled",
  "disabledReason": null,
  "disabledAt": null,
  "apiVersion": "v1",
  "apiKeyId": "0190f3a4-1d2e-7a55-8c10-3b9e4f6a2d08",
  "secretRotationEndsAt": null,
  "lastDelivery": null,
  "createdAt": "2026-11-12T08:00:00Z",
  "updatedAt": "2026-11-12T08:00:00Z",
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSwMfKQ9r8GKYo="
}
```

Das Secret steht in dieser Antwort und in der Antwort auf einen [Wechsel](#das-secret-wechseln), sonst nirgends. Speichere es sofort. Spätere Abrufe zeigen es nicht.

Die Adresse muss `https` sein, auf eine öffentliche Adresse zeigen und darf keinen Benutzernamen enthalten. Athaus prüft das beim Anlegen und noch einmal vor jeder Zustellung, denn ein Name kann bis dahin woanders hin zeigen. Rechner im eigenen Netz, `localhost` und die Metadaten-Adresse eines Cloud-Anbieters sind kein Ziel. Ein Büro hat höchstens 20 Endpunkte (`webhook_endpoint_limit_exceeded`).

`POST /v1/webhookEndpoints` und der Wechsel des Secrets nehmen keinen `Idempotency-Key`: Die Antwort trägt ein Secret, das nie gespeichert wird. Ging eine Antwort verloren, lösche den Endpunkt und lege ihn neu an.

## Scopes [#scopes]

Der Key braucht den Scope `propose`, die Stufe `write` auf `webhookEndpoints` und die Stufe `read` auf der Ressource jedes Ereignisses, das du abonnierst ([Scopes und Stufen](/api/v1/anmeldung#scopes)). Wer mehr verlangt, bekommt `403` (`insufficient_permissions`); Ereignisse fallen nie stillschweigend weg. Die Prüfung gilt bei jeder Änderung des Endpunkts.

`webhookEndpoints` bekommt nur ein Key, den die Leitung des Büros angelegt hat, wie `contacts`.

Der Endpunkt gehört dem Key, der ihn angelegt hat. Wird dieser Key widerrufen oder endet er, weil seine Person das Büro verlässt, hört der Endpunkt auf zuzustellen; `GET` zeigt `disabledReason: key_revoked`. Die [Key-Liste](/api/v1/anmeldung) ist der eine Ort, an dem du Zugriff beendest.

## Ereignisse [#ereignisse]

| Typ                | Wann                                                                             | Ressource   | Stufe  |
| ------------------ | -------------------------------------------------------------------------------- | ----------- | ------ |
| `inquiry.received` | eine Anfrage ist eingegangen                                                     | `inquiries` | `read` |
| `message.received` | eine Nachricht zu einer Anfrage ist eingegangen                                  | `inquiries` | `read` |
| `viewing.booked`   | eine Besichtigung wurde gebucht                                                  | `viewings`  | `read` |
| `viewing.canceled` | ein Gast hat abgesagt                                                            | `viewings`  | `read` |
| `viewing.upcoming` | eine Besichtigung beginnt bald                                                   | `viewings`  | `read` |
| `file.processed`   | ein Dokument zu einem Inserat wurde gelesen                                      | `files`     | `read` |
| `project.created`  | ein Projekt wurde angelegt                                                       | `projects`  | `read` |
| `project.updated`  | ein Projekt wurde geändert oder entfernt                                         | `projects`  | `read` |
| `proposal.pending` | ein Vorschlag aus [Was das Büro verlässt](/api/v1/hinausgehen) wartet auf ein Ja | `inquiries` | `read` |

Das sind dieselben Namen wie bei den [MCP-Ereignissen](/mcp/ereignisse). `proposal.pending` bekommt nur der Endpunkt des Keys, der den Vorschlag angelegt hat, so wie `GET /v1/proposals` nur die Vorschläge dieses Keys zeigt; `data.object` ist der Vorschlag. Für Änderungen an Inseraten und Kontakten gibt es kein Ereignis; verfolge sie mit `updatedSince` ([Blättern](/api/v1/blaettern)). Neue Typen kommen ohne neue Version: Überlies, was du nicht kennst.

## Was ankommt [#was-ankommt]

Ein `POST` mit JSON an deine Adresse. Der Rumpf ist ein [Ereignis](/api/v1/ereignisse):

```json
{
  "object": "event",
  "id": "0190f3c1-22aa-7d10-9b3e-0f8e5c6a1d44",
  "type": "inquiry.received",
  "createdAt": "2026-11-12T08:14:03.512Z",
  "apiVersion": "v1",
  "livemode": true,
  "data": {
    "object": {
      "object": "inquiry",
      "id": "0190f3c1-2217-7a02-8c4b-5e1d7a9b3f10",
      "listingId": "0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17",
      "status": "new",
      "source": "athaus",
      "answered": false,
      "replyable": true,
      "name": "Mia K.",
      "email": null,
      "phone": null,
      "contactId": null,
      "contactConsent": "not_requested",
      "seeker": null,
      "createdAt": "2026-11-12T08:14:03Z",
      "updatedAt": "2026-11-12T08:14:03Z"
    }
  }
}
```

`data.object` ist die Anfrage, wie `GET /v1/inquiries/{id}` sie liefert. Sie hat den Stand des Moments, in dem Athaus zustellt. Gibt es sie nicht mehr, kommt stattdessen `{ "object": "inquiry", "id": "...", "deleted": true }`.

`livemode` ist `false` bei einem Endpunkt, den du mit einem Test-Key anlegst: Er gehört zum [Testbüro](/api/v1/testmodus), bekommt dessen Ereignisse und wird genauso signiert. Webhooks sind das Einzige, was das Testbüro verlässt.

Drei Köpfe kommen mit, wie Standard Webhooks sie beschreibt:

| Kopf                | Inhalt                                                                                        |
| ------------------- | --------------------------------------------------------------------------------------------- |
| `webhook-id`        | die Id des Ereignisses, bei jeder Wiederholung dieselbe                                       |
| `webhook-timestamp` | Unix-Sekunden dieses Versuchs, bei jedem Versuch neu                                          |
| `webhook-signature` | `v1,` und die Signatur in Base64; zwei während eines Wechsels, durch ein Leerzeichen getrennt |

## Die Signatur prüfen [#die-signatur-prüfen]

Prüfe jede Zustellung, bevor du ihr traust. Die Signatur ist HMAC-SHA256 über `{webhook-id}.{webhook-timestamp}.{body}` mit dem Secret (ohne `whsec_`, Base64-dekodiert). Berechne sie über die Bytes, die ankamen, nicht über neu serialisiertes JSON.

```js
import { createHmac, timingSafeEqual } from "node:crypto";
import express from "express";

function genuine(body, headers, secret) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) return false;
  // Eine Zustellung, die älter als fünf Minuten ist, wird nicht angenommen.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest();
  return signatures.split(" ").some((s) => {
    const [version, value] = s.split(",");
    if (version !== "v1" || !value) return false;
    const given = Buffer.from(value, "base64");
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}

const app = express();
app.post("/hooks/athaus", express.raw({ type: "application/json" }), (req, res) => {
  if (!genuine(req.body.toString("utf8"), req.headers, process.env.ATHAUS_WEBHOOK_SECRET)) return res.sendStatus(400);
  const event = JSON.parse(req.body.toString("utf8"));
  // Dieselbe webhook-id kann mehrfach ankommen: Verarbeite jedes Ereignis einmal.
  res.sendStatus(200);
});
```

Antworte schnell und arbeite danach. Fertige Bibliotheken für Standard Webhooks prüfen dasselbe.

## Antworten und Wiederholungen [#antworten-und-wiederholungen]

Antworte binnen 10 Sekunden mit einer beliebigen `2xx`. Athaus liest den Rumpf deiner Antwort nicht und folgt keiner Weiterleitung. Jede andere Antwort, eine Zeitüberschreitung oder ein Verbindungsfehler gilt als nicht zugestellt und wird wiederholt. Die Zustellung ist mindestens einmal, eine Wiederholung erkennst du also an der `webhook-id`.

| Versuch | Wann                         |
| ------- | ---------------------------- |
| 1       | sofort                       |
| 2       | 1 Minute nach dem ersten     |
| 3       | 5 Minuten nach dem zweiten   |
| 4       | 30 Minuten nach dem dritten  |
| 5       | 2 Stunden nach dem vierten   |
| 6       | 6 Stunden nach dem fünften   |
| 7       | 12 Stunden nach dem sechsten |
| 8       | 24 Stunden nach dem siebten  |
| 9       | 24 Stunden nach dem achten   |

Jeder Abstand kann bis zu ein Zehntel länger sein. Zusammen sind das etwa drei Tage. Scheitert auch der neunte Versuch, lässt Athaus dieses eine Ereignis fallen; es bleibt über [`GET /v1/events`](/api/v1/ereignisse) abrufbar. Ein `413` tut dasselbe sofort, ein `410` des Empfängers schaltet den Endpunkt sofort ab. Was geschieht, wenn nie etwas durchkommt, steht unter [Wenn dein Endpunkt ausfällt](#ausfall).

`GET /v1/webhookEndpoints/{id}` zeigt, ob ein Endpunkt zustellt:

| Mitglied         | Bedeutung                                                                                                         |
| ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `status`         | `enabled` oder `disabled`                                                                                         |
| `disabledReason` | `disabled_by_user`, `target_not_allowed`, `endpoint_gone`, `delivery_failing` oder `key_revoked`                  |
| `disabledAt`     | seit wann er abgeschaltet ist, von dir oder von Athaus; `null`, solange er zustellt                               |
| `lastDelivery`   | Zeit (`at`), HTTP-Status und Art des Fehlers beim letzten Versuch; `failingSince` sagt, seit wann alles scheitert |

## Wenn dein Endpunkt ausfällt [#ausfall]

Athaus führt für jeden Endpunkt eine Uhr: den ersten fehlgeschlagenen Versuch seit der letzten erfolgreichen Zustellung (`lastDelivery.failingSince`).

* Eine einzige `2xx` setzt die Uhr zurück, auch wenn andere Ereignisse noch wiederholt werden.
* Nach einem Tag ohne Erfolg schreibt Athaus der Leitung des Büros (Inhaber und Admin) eine E-Mail: Der Endpunkt scheitert, und wann er abgeschaltet wird. Die E-Mail kommt einmal je Ausfall.
* Nach fünf Tagen ohne Erfolg schaltet Athaus den Endpunkt ab. `status` ist `disabled`, `disabledReason` ist `delivery_failing`, `disabledAt` nennt die Zeit. Eine zweite E-Mail sagt das, mit der Adresse (ohne Pfad), dem letzten Fehler und dem Weg zurück. Zustellungen, die noch warten, werden nicht mehr versucht.
* War in diesen fünf Tagen nichts fällig, bleibt der Endpunkt an. Die Uhr läuft nur, solange Zustellungen scheitern.

Die E-Mail geht an die Leitung und nicht an den, der den Key ausgestellt hat, so erreicht sie jemanden, auch wenn der Aussteller das Büro verlassen hat.

Abgeschaltet heißt nicht verloren. Die Ereignisse der letzten 30 Tage holst du über [`GET /v1/events`](/api/v1/ereignisse) nach. Schalte den Endpunkt mit `PATCH` und `{ "disabled": false }` wieder an, sobald dein Empfänger läuft; die Adresse wird neu geprüft, und die Uhr beginnt von vorn.

## Das Secret wechseln [#das-secret-wechseln]

```bash
curl -X POST https://api.athaus.ai/v1/webhookEndpoints/0190f3b0-5a71-7c3e-8f12-6d0a9e4b7c21/rotateSecret \
  -H "Authorization: Bearer ath_live_..."
```

Die Antwort trägt das neue Secret, einmal. Das vorige signiert noch 24 Stunden weiter (`secretRotationEndsAt` nennt das Ende): In dieser Zeit hat jede Zustellung zwei Signaturen, und ein Empfänger, der eines der beiden Secrets kennt, nimmt sie an. So tauschst du das Secret auf deiner Seite, ohne dass eine Zustellung scheitert. Wechselst du innerhalb der 24 Stunden noch einmal, wird das bisher aktuelle zum vorigen.

## Testen, ändern, löschen [#testen-ändern-löschen]

* `POST /v1/webhookEndpoints/{id}/test` schickt genau einmal ein Ereignis vom Typ `webhook_endpoint.test` und antwortet mit dem Ergebnis (`delivered`, `status`, `error`). Es wiederholt nichts und lässt den Zustand des Endpunkts, wie er ist.
* `PATCH` ändert `url`, `events`, `description` und `disabled` als Merge Patch.
* `DELETE` entfernt den Endpunkt.
* `GET /v1/webhookEndpoints` listet die Endpunkte des Büros, die neuesten zuerst.

Jede Operation steht in der [Referenz](/api/v1/referenz).
