Webhooks

Mit Webhooks meldet HELLO OS Ereignisse direkt an Ihre eigenen Systeme, z. B. an ein CRM oder eine Bewirtschaftungssoftware. Tritt ein abonniertes Ereignis ein, sendet HELLO OS eine signierte POST-Anfrage an eine URL, die Sie festlegen. Sie finden die Seite unter Mandant › Integrationen › Webhooks.

Voraussetzungen

• Rolle Mandantenadmin oder Entwickler.
• Ein Endpunkt Ihres Systems, der aus dem Internet über HTTPS erreichbar ist.

Webhooks gelten für den ganzen Mandanten, nicht für ein einzelnes Projekt. Ein Webhook erhält die Ereignisse aller Einheiten, für die Ihr Mandant zuständig ist: als Eigentümer oder über ein laufendes Mandat.

Webhook anlegen

1. Klicken Sie auf Webhook hinzufügen.
2. Erfassen Sie Name und Payload-URL.
3. Lassen Sie Secret leer, damit HELLO OS eines erzeugt, oder geben Sie ein eigenes mit mindestens 16 Zeichen ein.
4. Wählen Sie unter Ereignisse mindestens ein Ereignis.
5. Klicken Sie auf Webhook erstellen.
6. Kopieren Sie das angezeigte Secret mit Kopieren und hinterlegen Sie es in Ihrem System. Es wird nur dieses eine Mal angezeigt. Schliessen Sie den Hinweis mit Ich habe es gespeichert.

Die URL muss https verwenden, darf weder Benutzername noch Passwort enthalten und nicht in ein privates Netzwerk zeigen. Pro URL ist nur ein Webhook möglich, pro Mandant höchstens 20.

Bearbeiten, abschalten, löschen

Im Zeilenmenü eines Webhooks wählen Sie Bearbeiten, Test senden oder Löschen.

• Beim Bearbeiten ändern Sie Name, URL, Ereignisse und den Schalter Aktiv. Speichern Sie mit Speichern. Das gespeicherte Secret wird nie angezeigt; lassen Sie das Feld leer, bleibt es erhalten.
• Neues Secret erzeugen erzeugt nach einer Rückfrage ein neues Secret und zeigt es einmal an. Das bisherige ist sofort ungültig.
• Löschen erfordert eine Bestätigung. Ihr System erhält danach keine Ereignisse mehr.

Die Spalte Status zeigt Aktiv, Inaktiv oder Nach Fehlern abgeschaltet.

Ereignisse

Diese Ereignisse werden heute gesendet:

Ereignis	Kennung	Wann
Interesse eingegangen	interest.created	Ein neuer Lead ist eingegangen.
Nachricht eingegangen	message.received	Eine Nachricht von aussen ist eingegangen. Eigene Nachrichten und interne Notizen lösen nichts aus.
Bewerbung eingereicht	application.submitted	Eine Bewerbung wurde eingereicht.
Besichtigung gebucht	viewing.booked	Eine Besichtigung wurde gebucht.
Besichtigung storniert	viewing.cancelled	Eine Besichtigung wurde storniert.
Vertrag unterzeichnet	contract.signed	Die Mieterseite hat unterschrieben, die Gegenzeichnung steht aus.
Vertrag abgeschlossen	contract.completed	Der Vertrag ist von beiden Seiten unterschrieben.

Alle weiteren Ereignisse im Formular tragen den Zusatz demnächst und lassen sich noch nicht wählen.

Zustellung, Wiederholungen und Protokoll

Eine Zustellung gilt als erfolgreich, wenn Ihr Endpunkt innert 10 Sekunden mit einem 2xx-Status antwortet. Weiterleitungen (3xx) werden nicht verfolgt und zählen als Fehler. Nach einem Fehler versucht HELLO OS es nach 1, 5, 15, 30 und 60 Minuten erneut, insgesamt also sechs Mal. Danach wird die Zustellung aufgegeben.

Werden fünf Zustellungen in Folge aufgegeben, schaltet HELLO OS den Webhook ab. Beheben Sie den Fehler am Endpunkt und schalten Sie den Webhook wieder auf Aktiv. Damit beginnt die Fehlerzählung von vorn.

Beim Bearbeiten zeigt Letzte Zustellungen die 20 neuesten Zustellungen mit Status, Ereignis, HTTP-Antwort oder Fehler, Versuch (z. B. 2/6) und Zeitpunkt. Abgeschlossene Zustellungen bleiben 30 Tage im Protokoll.

Testen

Test senden sendet sofort ein Ereignis webhook.ping und meldet Test zugestellt oder Test nicht zugestellt. Der Test funktioniert auch bei einem inaktiven Webhook, zählt nicht zur Fehlerzählung und erscheint im Protokoll. Pro Mandant sind sechs Tests pro Minute möglich.

Für Ihre Entwicklerinnen und Entwickler

Jede Anfrage ist ein POST mit JSON-Body (höchstens 256 KB):

{
  "id": "0b6f…",
  "type": "application.submitted",
  "occurredAt": "2026-09-23T08:15:00.000Z",
  "version": 1,
  "organizationId": 42,
  "projectId": 1234,
  "data": { "applicationId": 987, "unitId": 555 }
}

data enthält nur Kennungen, keine Personendaten. Je nach Ereignis: interestId, unitId, objectId (Lead); messageId, conversationId, entityType, entityId (Nachricht); applicationId, unitId (Bewerbung, Vertrag); bookingId, slotId, unitId, startsAt (Besichtigung). Der Test liefert subscriptionId.

Header:

• X-Beyonity-Event: die Kennung des Ereignisses
• X-Beyonity-Event-Id: die id aus dem Body, bei Wiederholungen unverändert
• X-Beyonity-Delivery: die Nummer der Zustellung
• X-Beyonity-Timestamp: Unix-Zeit in Sekunden
• X-Beyonity-Signature: sha256= gefolgt vom hexadezimalen HMAC-SHA256
• User-Agent: Beyonity-Webhooks/1

Die Signatur ist der HMAC-SHA256 über <Timestamp>.<Body>, mit dem ganzen Secret (inklusive Präfix whsec_) als Schlüssel. Rechnen Sie ihn über die unveränderten Bytes des Bodys nach, vergleichen Sie zeitkonstant und lehnen Sie Anfragen mit einem Timestamp ab, der älter als wenige Minuten ist:

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const ts = headers["x-beyonity-timestamp"];
  const expected = "sha256=" + crypto.createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`).digest("hex");
  const given = headers["x-beyonity-signature"] || "";
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  return fresh && given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected));
}

Gut zu wissen

• Ein Ereignis kann mehrfach ankommen, z. B. wenn Ihre Antwort nach dem Timeout eintrifft. Erkennen Sie Duplikate an X-Beyonity-Event-Id.
• In seltenen Fällen kann ein Ereignis verloren gehen. Nutzen Sie Webhooks als Auslöser und gleichen Sie wichtige Daten über die API ab.
• Das Feld organizationId im Body hiess bis Oktober 2026 mandantId. Ein Empfänger, der noch mandantId liest, muss angepasst werden.

Verwandte Seiten

• Partner-Benachrichtigungen
• Rollen & Berechtigungen
• Projekt-Setup