Benachrichtigungen an Verwaltungssoftware

Wenn Sie mit einer Verwaltungssoftware oder einem Automatisierungstool wie Zapier oder Make arbeiten, können Sie diese sofort benachrichtigen, sobald eine Buchung eingeht, geändert oder storniert wird, sowie wenn der Gast an- oder abreist. Kein manuelles Übertragen von Daten mehr.

Wozu dienen die Benachrichtigungen

Jedes Mal, wenn sich der Status einer Buchung ändert, sendet Roraima eine kurze Nachricht an die von Ihnen angegebene Adresse. Ihre Verwaltungssoftware empfängt diese und aktualisiert sich von selbst: Sie markiert das Zimmer als belegt, bereitet die Reinigung vor, schreibt den Gast an oder aktualisiert die Abrechnung. Alles, was Sie früher durch manuelles Abgleichen und Abtippen erledigt haben, übernimmt jetzt das Programm, das Sie bereits verwenden.

Wo man sie aktiviert

Öffnen Sie im Dashboard das Menü Verbindungen und wählen Sie Benachrichtigungen an Verwaltungssoftware. Dort fügen Sie die Adresse ein, die Ihnen Ihre Verwaltungssoftware bereitstellt (diese finden Sie normalerweise in den Einstellungen unter dem Punkt für eingehende Verbindungen), geben ihr einen Namen zur besseren Wiedererkennung und wählen aus, welche Benachrichtigungen gesendet werden sollen: Buchung bestätigt, Buchung geändert, Buchung storniert, Ankunft erfasst, Abreise erfasst, Gast nicht erschienen. Beim Speichern prüft Roraima sofort, ob die Adresse korrekt formatiert und über das Internet erreichbar ist. Sie können bis zu fünf Adressen verknüpfen, zum Beispiel Ihre Verwaltungssoftware und eine von Zapier verwaltete Tabelle.

Jede Adresse hat ihren eigenen Signaturschlüssel, den Sie jederzeit einsehen können: Öffnen Sie unter der Adresse «Signaturschlüssel» und klicken Sie auf «Anzeigen», dann erscheint der Schlüssel auf einer eigenen Seite. Er muss an die Verwaltungssoftware oder den zuständigen Techniker weitergegeben werden: Er dient dazu, dass das System erkennt, dass die Nachricht tatsächlich von Roraima stammt. Behandeln Sie ihn wie ein Passwort. Falls Sie vermuten, dass er in falsche Hände geraten ist, klicken Sie auf «Neuen Schlüssel erstellen»: Der alte funktioniert sofort nicht mehr und der neue, den Sie wieder mit «Anzeigen» sehen, muss in der Verwaltungssoftware hinterlegt werden.

Wenn Sie die Verwaltung Ihres Objekts einem Verwalter mit aktiver Vollmacht übertragen haben, kann auch dieser seine eigene Verwaltungssoftware anbinden und die Benachrichtigungen für die Buchungen erhalten, die er für Sie betreut.

Gastdaten, nur wenn nötig

Standardmäßig enthält die Nachricht alles, was zur Organisation des Aufenthalts nötig ist: Unterkunft oder Bereich, Daten, Uhrzeit, Personenanzahl, Betrag und Buchungsstatus. Name, E-Mail und Telefonnummer des Gastes bleiben außen vor.

Falls Ihre Verwaltungssoftware diese benötigt, beispielsweise um eine Willkommensnachricht zu senden oder das Gästeblatt auszufüllen, aktivieren Sie das Feld Name, E-Mail und Telefonnummer des Gastes mitsenden für die jeweilige Adresse. Es ist absichtlich deaktiviert: Sie schalten es gezielt, Adresse für Adresse, nur dort ein, wo es wirklich gebraucht wird.

Ein Test vor dem Start

Neben jeder aktiven Adresse befindet sich die Schaltfläche Test senden. Roraima sendet sofort eine Beispielnachricht mit dem gleichen Format wie die echten, aber mit fiktiven Daten. Das Ergebnis erscheint sofort oben auf der Seite und in der Liste der letzten Sendungen. Keine echte Buchung wird dabei verändert, und Sie können den Test beliebig oft wiederholen, während Sie die Verbindung einrichten.

Wenn die Verwaltungssoftware nicht antwortet

Das kann passieren: Der Server der Verwaltungssoftware ist in Wartung, die Verbindung bricht ab oder eine Einstellung wurde geändert. Roraima verliert die Benachrichtigung nicht und versucht es von selbst erneut, in immer größeren Abständen, von einer Minute bis zu einem ganzen Tag, über fast zwei Tage hinweg.

Sollte die Adresse jedoch 24 Stunden lang nur Fehler zurückgeben, setzt Roraima sie aus und sendet Ihnen eine E-Mail zur Benachrichtigung. Sobald die Verwaltungssoftware wieder erreichbar ist, klicken Sie neben der Adresse auf Fortsetzen und die Benachrichtigungen starten wieder. Dieselbe Schaltfläche erscheint nach «Pausieren», was Sie nutzen können, wenn Sie den Versand für eine Weile stoppen möchten, zum Beispiel während eines Wechsels der Verwaltungssoftware: Benachrichtigungen über Buchungen, die sich während der Pause ändern, werden nicht gesendet, und alles nimmt seinen Lauf ab dem Moment, in dem Sie die Verbindung wieder aktivieren.

In der Liste Zuletzt gesendet finden Sie die letzten zwanzig Benachrichtigungen aller Ihrer Adressen, mit Datum, Art der Benachrichtigung, Buchung, Adresse und Ergebnis: Zugestellt, Wartet auf einen neuen Versuch oder Nicht zugestellt, wobei im letzten Fall auch der Grund angegeben wird.

Für Entwickler der Schnittstelle

Jede Benachrichtigung ist ein POST-Request mit einem JSON-Body, ein Ereignis pro Request, gesendet an die vom Eigentümer registrierte Adresse. Dies sind die Header, die jedes Mal eintreffen:

Content-Type: application/json
User-Agent: Roraima-Webhooks/1.0
Roraima-Event-Id: evt_5f2c9a1e7b3d4c6f8a0b1c2d3e4f5a6b
Roraima-Event-Type: booking.confirmed
Roraima-Signature: t=1791986607,v1=5d41402abc4b2a76b9719d911017c592ae51ec1e4d1a8c67b2f0d7d8a3e9c410

Roraima-Event-Id ist derselbe Wert wie das Feld id im Body, und Roraima-Event-Type entspricht dem Feld type: Sie können entscheiden, wie Sie mit einer Benachrichtigung verfahren, noch bevor Sie den Body lesen.

Die Ereignisse

• booking.confirmed: eine Buchung wurde bestätigt. Gilt auch für Buchungen von anderen verknüpften Kanälen und manuell eingetragene Buchungen. Sie kann auch für eine Buchung eintreffen, die Ihr System bereits kennt: wenn der Herkunftskanal sie nach einer Stornierung wieder gültig macht oder wenn sie wieder gültig wird, nachdem der Eigentümer eine Überschneidung mit einer anderen Buchung aufgelöst hat. In diesen Fällen gibt previous_status an, aus welchem Status sie zurückkehrt: Aktualisieren Sie die Buchung mit derselben booking.id, statt eine neue anzulegen.
• booking.modified: Daten, Uhrzeit oder Personenanzahl haben sich geändert. Das Feld changes gibt Details dazu an.
• booking.cancelled: die Buchung wurde storniert. cancelled_by gibt an, ob die Stornierung von Roraima oder vom Ursprungskanal ausging.
• booking.checked_in: der Gast ist angekommen.
• booking.checked_out: der Gast ist abgereist. Wenn die Abreise automatisch bei Ablauf erfolgte, ist closed_automatically auf true gesetzt.
• booking.no_show: der Gast ist nicht erschienen.

Der Eigentümer wählt im Dashboard aus, welche Ereignisse an welche Adresse gesendet werden: Wenn Sie einen Typ nicht benötigen, können Sie ihn bitten, diesen deaktiviert zu lassen.

Ein vollständiges Beispiel

Der Body kommt kompakt in einer Zeile an; hier ist er zur besseren Lesbarkeit formatiert. Die Felder können sich im Laufe der Zeit erweitern, aber die vorhandenen ändern weder Namen noch Bedeutung, solange die api_version gleich bleibt: Ignorieren Sie einfach Felder, die Sie nicht kennen.

{
  "id": "evt_5f2c9a1e7b3d4c6f8a0b1c2d3e4f5a6b",
  "type": "booking.confirmed",
  "created_at": "2026-10-02T14:03:27Z",
  "api_version": "2026-09-30",
  "test": false,
  "data": {
    "booking": {
      "id": 4812,
      "company_id": 37,
      "status": "confirmed",
      "previous_status": "pending",
      "source": "native",
      "external_id": null,
      "product": { "id": 16702211, "name": "Camera Mirto" },
      "structure_id": 12,
      "check_in": "2026-10-16",
      "check_out": "2026-10-19",
      "booking_mode": "daily",
      "time_slot": null,
      "guests": 2,
      "amount": "390.00",
      "currency": "EUR",
      "cancelled_by": null,
      "closed_automatically": false,
      "sequence": 90417
    },
    "changes": null,
    "actor": "buyer",
    "guest": {
      "name": "Anna Keller",
      "email": "[email protected]",
      "phone": "+491701234567"
    }
  }
}

Bei einem booking.modified enthält changes nur die geänderten Felder, jeweils mit dem vorherigen und dem neuen Wert:

"changes": {
  "check_out": { "from": "2026-10-19", "to": "2026-10-20" },
  "guests": { "from": 2, "to": 3 }
}

Die Bedeutung der booking-Felder:

• status und previous_status: der Status nach dem Ereignis und der davor. Bei einem booking.modified, bei dem sich der Status nicht ändert, sind beide identisch. previous_status ist nur dann null, wenn eine Buchung bereits bestätigt erstellt wurde, manuell eingetragen oder von einem verknüpften Kalender stammt.
• source: woher die Buchung stammt. native aus dem Roraima-Shop, manual manuell eingetragen, ical_airbnb, ical_booking_com, ical_vrbo oder ical_generic von einem verknüpften Kalender.
• external_id: bei Buchungen von einem verknüpften Kalender die Kennung, die dieser Kalender vergeben hat; ansonsten null.
• check_in und check_out: die Daten im Format YYYY-MM-DD. Bei stundenweisen Buchungen ist booking_mode auf hourly gesetzt und time_slot enthält die Uhrzeit, z. B. {"from": "10:00", "to": "12:00"}.
• guests: die für den Aufenthalt angemeldeten Personen.
• amount und currency: der Betrag als Text mit zwei Dezimalstellen und die Währung; beides null, wenn die Buchung keinen Betrag hat, wie es oft bei Kalenderbuchungen der Fall ist.
• actor: wer das Ereignis ausgelöst hat. guest, buyer, vendor (der Eigentümer), manager (ein Verwalter mit Vollmacht), admin, channel (ein verknüpfter Kalender) oder system.
• guest: Name, E-Mail und Telefonnummer des Gastes, nur wenn der Eigentümer das Feld für diese Adresse aktiviert hat; ansonsten null.

Signaturprüfung

Jeder Request ist mit dem Signaturschlüssel der Adresse signiert, der mit whsec_ beginnt. Der Header Roraima-Signature hat das Format t=<timestamp>,v1=<hex>, wobei v1 der HMAC-SHA256 von t, einem Punkt und dem Request-Body ist, berechnet mit dem vollständigen Schlüssel inklusive Präfix.

Drei Punkte sind entscheidend: Berechnen Sie die Signatur auf dem rohen Body, genau wie er angekommen ist, niemals auf einem neu geparsten und serialisierten JSON; vergleichen Sie die beiden Signaturen mit einem zeitkonstanten Vergleich; lehnen Sie den Request ab, wenn t mehr als 300 Sekunden von Ihrer Systemzeit abweicht. In PHP:

<?php
$secret = getenv('RORAIMA_WEBHOOK_SECRET'); // whsec_...
$body   = file_get_contents('php://input');
$header = $_SERVER['HTTP_RORAIMA_SIGNATURE'] ?? '';

if (!preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/', $header, $m)
    || abs(time() - (int) $m[1]) > 300
    || !hash_equals(hash_hmac('sha256', $m[1] . '.' . $body, $secret), $m[2])) {
    http_response_code(400);
    exit;
}

$event = json_decode($body, true);
// Save $event['id'] and skip it if you have already seen it,
// then reply at once and do the slow work afterwards.
http_response_code(200);

In Node, ohne externe Bibliotheken:

const http = require('node:http');
const crypto = require('node:crypto');

const SECRET = process.env.RORAIMA_WEBHOOK_SECRET; // whsec_...

function isValid(rawBody, header) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || '');
  if (!m) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(m[1])) > 300) return false;
  const expected = crypto.createHmac('sha256', SECRET)
    .update(m[1] + '.')
    .update(rawBody)
    .digest();
  return crypto.timingSafeEqual(expected, Buffer.from(m[2], 'hex'));
}

http.createServer((req, res) => {
  const chunks = [];
  req.on('data', (c) => chunks.push(c));
  req.on('end', () => {
    const rawBody = Buffer.concat(chunks);
    if (!isValid(rawBody, req.headers['roraima-signature'])) {
      res.writeHead(400).end();
      return;
    }
    const event = JSON.parse(rawBody.toString('utf8'));
    // Save event.id and skip it if you have already seen it,
    // then reply at once and do the slow work afterwards.
    res.writeHead(200).end();
  });
}).listen(3000);

Duplikate und Reihenfolge

Dieselbe Benachrichtigung kann mehrfach eintreffen, zum Beispiel wenn Ihre Antwort verloren geht und Roraima es erneut versucht. Speichern Sie die id jedes verarbeiteten Ereignisses und ignorieren Sie bereits bekannte IDs.

Durch die Wiederholungsversuche können zwei Benachrichtigungen derselben Buchung in einer anderen Reihenfolge eintreffen als sie passiert sind: ein booking.modified vor dem zugehörigen booking.confirmed. Um die Reihenfolge zu korrigieren, gibt es booking.sequence, eine Zahl, die mit jeder Benachrichtigung für dieselbe Buchung an dieselbe Adresse steigt. Behalten Sie die höchste bisher registrierte Zahl für jede Buchung und verwerfen Sie Benachrichtigungen mit einer niedrigeren Nummer. Die Nummern sind nicht zwingend fortlaufend: Zwischen zwei Benachrichtigungen können viele Nummern übersprungen werden.

Antworten und Wiederholungsversuche

Eine Benachrichtigung gilt als zugestellt, wenn Ihre Adresse mit einem 2xx-Code innerhalb von 5 Sekunden antwortet. Der Inhalt der Antwort wird nicht ausgewertet. Jedes andere Ergebnis zählt als fehlgeschlagener Versuch, einschließlich Weiterleitungen (3xx): Registrieren Sie die finale Adresse im Dashboard.

Nach einem fehlgeschlagenen Versuch probiert Roraima es nach 1 Minute erneut, dann nach 5, 15 Minuten, 1, 3, 6, 12 und 24 Stunden. Schlägt auch der letzte Versuch fehl, wird die Benachrichtigung als nicht zugestellt markiert. Wenn die Adresse 24 Stunden lang nur Fehler liefert, wird sie ausgesetzt, wartende Benachrichtigungen stoppen und der Eigentümer erhält eine E-Mail; der Versand startet wieder, wenn der Eigentümer auf «Fortsetzen» klickt. Benachrichtigungen, die während der Aussetzung oder Pause anfallen, werden nicht gesendet.

Um das 5-Sekunden-Limit einzuhalten, ist der sicherste Weg, sofort nach der Signaturprüfung und der Registrierung des Ereignisses zu antworten und zeitaufwendige Aufgaben erst danach auszuführen.

Die Test-Benachrichtigung

Die Schaltfläche «Test senden», die bei aktiven Adressen verfügbar ist, sendet ein booking.confirmed im gleichen Format wie echte Benachrichtigungen, identisch signiert, mit "test": true, einer booking.id von 0 und fiktiven Daten. Falls für die Adresse Gastdaten aktiviert sind, sind auch diese fiktiv. Der Test wird nur einmal versucht und das Ergebnis erscheint sofort im Dashboard. Prüfen Sie das test-Flag, bevor Sie in Ihrem System Datensätze anlegen.

Erkennen von Benachrichtigungen aus der eigenen Verwaltungssoftware

Wenn Ihre Verwaltungssoftware bereits Buchungen über einen verknüpften Kalender an Roraima sendet, kommen die Benachrichtigungen für diese Buchungen auch wieder bei Ihnen an. Nutzen Sie zur Identifizierung source und external_id: external_id ist die Kennung, die Ihr Kalender der Buchung gegeben hat, dieselbe, die Sie bereits kennen.

Anforderungen an die Adresse

Das Dashboard prüft diese bereits beim Speichern, und Roraima kontrolliert sie bei jedem Versand:

• Beginnt mit https://, mit einem gültigen Zertifikat, auf Port 443.
• Enthält nur den Domainnamen und den Pfad, ohne Benutzername und Passwort in der URL.
• Der Domainname ist öffentlich und über das Internet erreichbar.