REST-API: Webhooks
Ereignisse an eine Adresse deines Systems: einrichten, die Signatur prüfen, Wiederholungen verstehen, das Secret wechseln.
Zuletzt aktualisiert:
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.
Einrichten
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:
{
"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, 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
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). 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 ist der eine Ort, an dem du Zugriff beendest.
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 wartet auf ein Ja | inquiries | read |
Das sind dieselben Namen wie bei den MCP-Ereignissen. 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). Neue Typen kommen ohne neue Version: Überlies, was du nicht kennst.
Was ankommt
Ein POST mit JSON an deine Adresse. Der Rumpf ist ein Ereignis:
{
"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, 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
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.
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
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 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.
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
Athaus führt für jeden Endpunkt eine Uhr: den ersten fehlgeschlagenen Versuch seit der letzten erfolgreichen Zustellung (lastDelivery.failingSince).
- Eine einzige
2xxsetzt 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.
statusistdisabled,disabledReasonistdelivery_failing,disabledAtnennt 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 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
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
POST /v1/webhookEndpoints/{id}/testschickt genau einmal ein Ereignis vom Typwebhook_endpoint.testund antwortet mit dem Ergebnis (delivered,status,error). Es wiederholt nichts und lässt den Zustand des Endpunkts, wie er ist.PATCHänderturl,events,descriptionunddisabledals Merge Patch.DELETEentfernt den Endpunkt.GET /v1/webhookEndpointslistet die Endpunkte des Büros, die neuesten zuerst.
Jede Operation steht in der Referenz.
Weiter lesen
REST-API: Ereignisse
Was im Büro geschah, 30 Tage lang abrufbar. Dieselben Ereignisse, die an Webhooks gehen, gefiltert nach Typ und Zeit.
REST-API: Anmeldung mit einem API-Key
Jeder Aufruf von /v1 trägt einen API-Key als Bearer-Token. Wo du ihn bekommst, welche Scopes er trägt und was nicht geht.
REST-API: Fehler als Problem Details
Jeder Fehler von /v1 ist ein Problem nach RFC 9457 mit echtem HTTP-Status, einem Code zum Verzweigen und einer Request-Id für den Support.