AthausDoku

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

TypWannRessourceStufe
inquiry.receivedeine Anfrage ist eingegangeninquiriesread
message.receivedeine Nachricht zu einer Anfrage ist eingegangeninquiriesread
viewing.bookedeine Besichtigung wurde gebuchtviewingsread
viewing.canceledein Gast hat abgesagtviewingsread
viewing.upcomingeine Besichtigung beginnt baldviewingsread
file.processedein Dokument zu einem Inserat wurde gelesenfilesread
project.createdein Projekt wurde angelegtprojectsread
project.updatedein Projekt wurde geändert oder entferntprojectsread
proposal.pendingein Vorschlag aus Was das Büro verlässt wartet auf ein Jainquiriesread

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:

KopfInhalt
webhook-iddie Id des Ereignisses, bei jeder Wiederholung dieselbe
webhook-timestampUnix-Sekunden dieses Versuchs, bei jedem Versuch neu
webhook-signaturev1, 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.

VersuchWann
1sofort
21 Minute nach dem ersten
35 Minuten nach dem zweiten
430 Minuten nach dem dritten
52 Stunden nach dem vierten
66 Stunden nach dem fünften
712 Stunden nach dem sechsten
824 Stunden nach dem siebten
924 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:

MitgliedBedeutung
statusenabled oder disabled
disabledReasondisabled_by_user, target_not_allowed, endpoint_gone, delivery_failing oder key_revoked
disabledAtseit wann er abgeschaltet ist, von dir oder von Athaus; null, solange er zustellt
lastDeliveryZeit (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 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 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}/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.

Weiter lesen

Auf dieser Seite