Powiadomienia do programu do zarządzania

Jeśli korzystasz z programu do zarządzania lub narzędzi automatyzacji, takich jak Zapier czy Make, możesz otrzymywać powiadomienia w momencie, gdy rezerwacja zostanie utworzona, zmieniona, anulowana, a także gdy gość przyjedzie lub wyjedzie. Koniec z ręcznym przepisywaniem dat.

Do czego służą powiadomienia

Za każdym razem, gdy status rezerwacji ulega zmianie, Roraima wysyła krótką wiadomość na wskazany przez Ciebie adres. Twój program do zarządzania odbiera ją i aktualizuje dane: oznacza pokój jako zajęty, przygotowuje sprzątanie, pisze do gościa, aktualizuje rozliczenia. Wszystko to, co wcześniej robiłeś ręcznie, przeglądając panel, teraz wykonuje program, z którego już korzystasz.

Gdzie je włączyć

W panelu otwórz menu Połączenia i wybierz Powiadomienia do programu do zarządzania. Wklej tam adres otrzymany z programu do zarządzania (zazwyczaj znajduje się w ustawieniach, w sekcji dotyczącej połączeń przychodzących), nadaj mu nazwę, która ułatwi Ci jego identyfikację, i wybierz, jakie powiadomienia mają być wysyłane: Rezerwacja potwierdzona, Rezerwacja zmieniona, Rezerwacja anulowana, Przyjazd zarejestrowany, Wyjazd zarejestrowany, Gość się nie pojawił. Po zapisaniu Roraima od razu sprawdzi, czy adres jest poprawny i dostępny w Internecie. Możesz podłączyć do pięciu adresów, na przykład program do zarządzania i arkusz kalkulacyjny obsługiwany przez Zapier.

Każdy adres posiada swój klucz podpisu, który zobaczysz w dowolnym momencie: otwórz «Klucz podpisu» pod adresem i kliknij «Pokaż», a klucz pojawi się na osobnej stronie. Należy go przekazać do programu do zarządzania lub osobie, która go konfiguruje: służy on do rozpoznania, że wiadomość rzeczywiście pochodzi z Roraima. Traktuj go jak hasło. Jeśli podejrzewasz, że trafił w niepowołane ręce, kliknij «Utwórz nowy klucz»: stary przestanie działać, a nowy, który znowu zobaczysz przyciskiem «Pokaż», należy wprowadzić do programu.

Jeśli powierzyłeś dom zarządcy z aktywnym upoważnieniem, on również może podłączyć swój program do zarządzania i otrzymywać powiadomienia o rezerwacjach, którymi się dla Ciebie opiekuje.

Dane gościa, tylko jeśli są potrzebne

Domyślnie wiadomość zawiera wszystko, co niezbędne do organizacji pobytu: obiekt lub przestrzeń, daty, godzinę, liczbę osób, kwotę i status rezerwacji. Imię, nazwisko, e-mail i telefon gościa pozostają ukryte.

Jeśli Twój program do zarządzania ich potrzebuje, na przykład do wysłania wiadomości powitalnej lub wypełnienia karty gościa, zaznacz pole Dołącz imię i nazwisko, e-mail i telefon gościa dla danego adresu. Opcja ta jest domyślnie wyłączona: włączasz ją samodzielnie, adres po adresie, tylko tam, gdzie jest to naprawdę potrzebne.

Test przed rozpoczęciem

Obok każdego aktywnego adresu znajduje się przycisk Wyślij test. Roraima natychmiast wyśle przykładową wiadomość, o tej samej strukturze co prawdziwe, ale z wymyślonymi danymi. Wynik pojawi się od razu na górze strony oraz na liście ostatnich wysyłek. Żadna rezerwacja nie zostanie naruszona, a test możesz powtarzać dowolną liczbę razy podczas konfigurowania połączenia.

Jeśli program do zarządzania nie odpowiada

To się zdarza: serwer programu jest w trakcie konserwacji, połączenie zostało przerwane, ktoś zmienił ustawienia. Roraima nie traci powiadomienia i ponawia próbę samodzielnie, w coraz dłuższych odstępach czasu, od minuty do całego dnia, przez prawie dwie doby.

Jeśli jednak przez dwadzieścia cztery godziny z rzędu dany adres odpowiada tylko błędami, Roraima zawiesi go i wyśle Ci e-mail z powiadomieniem. Gdy program znów będzie osiągalny, kliknij Wznów obok adresu, a powiadomienia zaczną ponownie docierać. Ten sam przycisk służy po użyciu opcji Wstrzymaj, z której korzystasz, gdy chcesz na chwilę zatrzymać wysyłkę, na przykład podczas zmiany programu do zarządzania: powiadomienia o rezerwacjach, które zmienią się w trakcie przerwy, nie zostaną wysłane, a wszystko ruszy od momentu, w którym wznowisz działanie.

Na liście Ostatnie wysyłki znajdziesz dwadzieścia ostatnich powiadomień ze wszystkich Twoich adresów, wraz z datą, typem powiadomienia, rezerwacją, adresem i wynikiem: Dostarczone, Oczekuje na kolejną próbę lub Niedostarczone (w tym ostatnim przypadku również z podaniem przyczyny).

Dla programistów

Każde powiadomienie to żądanie POST z treścią JSON, jedno zdarzenie na żądanie, wysyłane na adres zarejestrowany przez właściciela. Oto nagłówki, które przychodzą za każdym razem:

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 to ta sama wartość co pole id w treści, a Roraima-Event-Type to to samo co pole type: możesz zdecydować, co zrobić z powiadomieniem, jeszcze przed przeczytaniem jego treści.

Zdarzenia

• booking.confirmed: rezerwacja została potwierdzona. Dotyczy również tych, które wpłynęły z innych połączonych kanałów oraz dodanych ręcznie. Może też dotrzeć dla rezerwacji, którą Twój system już zna: gdy kanał, z którego pochodzi, ponownie uznaje ją za ważną po wcześniejszym anulowaniu, albo gdy znów staje się ważna po tym, jak właściciel rozwiązał nakładanie się z inną rezerwacją. W takich przypadkach previous_status wskazuje, z jakiego statusu wraca: zaktualizuj rezerwację o tym samym booking.id, zamiast tworzyć nową.
• booking.modified: zmieniły się daty, godzina lub liczba osób. Pole changes wskazuje, co dokładnie.
• booking.cancelled: rezerwacja została anulowana. cancelled_by informuje, czy anulowanie nastąpiło z poziomu Roraima, czy z kanału źródłowego.
• booking.checked_in: gość przyjechał.
• booking.checked_out: gość wyjechał. Jeśli wyjazd został zamknięty automatycznie po upływie terminu, closed_automatically ma wartość true.
• booking.no_show: gość się nie pojawił.

Właściciel wybiera w panelu, jakie zdarzenia mają być wysyłane na dany adres: jeśli jakiś typ nie jest Ci potrzebny, możesz poprosić o jego wyłączenie.

Pełny przykład

Treść przychodzi w formie zwartej, w jednej linii; tutaj została sformatowana dla lepszej czytelności. Pola mogą z czasem przybywać, ale te obecne nie zmieniają nazwy ani znaczenia, dopóki zachowana jest ta sama api_version: ignoruj te, których nie znasz.

{
  "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"
    }
  }
}

Dla booking.modified, pole changes zawiera tylko zmienione pola, każde z wartością poprzednią i obecną:

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

Znaczenie pól w booking:

• status i previous_status: status po zdarzeniu i przed nim. W przypadku booking.modified, gdzie status się nie zmienia, oba są identyczne. previous_status ma wartość null tylko dla rezerwacji utworzonej jako już potwierdzona, dodanej ręcznie lub pochodzącej z połączonego kalendarza.
• source: źródło rezerwacji. native ze sklepu Roraima, manual dodana ręcznie, ical_airbnb, ical_booking_com, ical_vrbo lub ical_generic z połączonego kalendarza.
• external_id: dla rezerwacji z połączonego kalendarza, identyfikator nadany przez ten kalendarz; w przeciwnym razie null.
• check_in i check_out: daty w formacie RRRR-MM-DD. Dla rezerwacji godzinowych, booking_mode ma wartość hourly, a time_slot zawiera czas, np. {"from": "10:00", "to": "12:00"}.
• guests: liczba osób zadeklarowana na pobyt.
• amount i currency: kwota jako tekst z dwoma miejscami po przecinku oraz waluta; oba pola null, gdy rezerwacja nie ma określonej kwoty, co często zdarza się w przypadku rezerwacji z kalendarzy.
• actor: kto wywołał zdarzenie. guest, buyer, vendor (właściciel), manager (zarządca z upoważnieniem), admin, channel (połączony kalendarz) lub system.
• guest: imię, nazwisko, e-mail i telefon gościa, tylko jeśli właściciel włączył odpowiednią opcję dla danego adresu; w przeciwnym razie null.

Weryfikacja podpisu

Każde żądanie jest podpisane kluczem podpisu adresu, który zaczyna się od whsec_. Nagłówek Roraima-Signature ma postać t=<timestamp>,v1=<hex>, gdzie v1 to HMAC-SHA256 z t, kropki i treści żądania, obliczony przy użyciu pełnego klucza, wraz z przedrostkiem.

Trzy kwestie mają kluczowe znaczenie: obliczaj podpis na surowej treści, dokładnie w takiej formie, w jakiej dotarła, a nie na ponownie przetworzonym JSON-ie; porównuj oba podpisy w czasie stałym; odrzuć żądanie, jeśli t różni się o więcej niż 300 sekund od Twojego zegara. W 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);

W Node, bez zewnętrznych bibliotek:

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);

Duplikaty i kolejność otrzymywania

To samo powiadomienie może dotrzeć więcej niż raz, na przykład gdy Twoja odpowiedź zaginie w sieci i Roraima ponowi próbę. Rejestruj id każdego zdarzenia, które już obsłużyłeś, i ignoruj te, które się powtarzają.

Ponadto, przy ponownych próbach, dwa powiadomienia dotyczące tej samej rezerwacji mogą dotrzeć w innej kolejności, niż miały miejsce: booking.modified przed booking.confirmed. Aby uporządkować zdarzenia, służy booking.sequence, numer, który rośnie przy każdym powiadomieniu o tej samej rezerwacji na ten sam adres. Zachowaj ostatni zarejestrowany numer dla każdej rezerwacji i odrzucaj powiadomienia z niższym numerem. Numery nie są ciągłe: między jednym powiadomieniem a drugim może ich brakować wiele.

Odpowiedzi i ponowne próby

Powiadomienie uważa się za dostarczone, gdy Twój adres odpowie kodem 2xx w ciągu 5 sekund. Treść odpowiedzi nie jest analizowana. Każdy inny wynik liczony jest jako nieudana próba, w tym przekierowanie na inny adres (3xx): zarejestruj ostateczny adres w panelu.

Po nieudanej próbie Roraima ponawia ją po 1 minucie, następnie po 5 minutach, 15 minutach, 1 godzinie, 3 godzinach, 6 godzinach, 12 godzinach i 24 godzinach. Jeśli ostatnia próba również zakończy się niepowodzeniem, powiadomienie zostanie oznaczone jako niedostarczone. Jeśli adres odpowiada tylko błędami przez 24 godziny z rzędu, zostanie zawieszony, oczekujące powiadomienia zostaną wstrzymane, a właściciel otrzyma e-mail; działanie zostanie wznowione, gdy właściciel kliknie «Wznów». Powiadomienia powstałe w czasie, gdy adres jest zawieszony lub wstrzymany przez właściciela, nie są wysyłane.

Aby zmieścić się w 5 sekundach, najbezpieczniej jest odpowiedzieć natychmiast po sprawdzeniu podpisu i zarejestrowaniu zdarzenia, a czasochłonne operacje wykonać w późniejszym czasie.

Powiadomienie testowe

Przycisk «Wyślij test», dostępny przy aktywnych adresach, wysyła booking.confirmed o tej samej strukturze co prawdziwe, podpisane w ten sam sposób, z "test": true, booking.id równym 0 i wymyślonymi danymi. Jeśli dla adresu włączono dane gościa, one również będą wymyślone. Test jest wykonywany tylko raz, a wynik pojawia się od razu w panelu. Sprawdź pole test przed utworzeniem czegokolwiek w swoim systemie.

Rozpoznawanie danych z własnego programu

Jeśli Twój program do zarządzania wysyła już swoje rezerwacje do Roraima poprzez połączony kalendarz, powiadomienia o tych rezerwacjach wrócą również do niego. Aby je rozpoznać, użyj source oraz external_id: external_id to identyfikator, który Twój kalendarz nadał rezerwacji, ten sam, który już znasz.

Wymagania dla adresu

Panel sprawdza je już w momencie zapisu, a Roraima weryfikuje je przy każdej wysyłce:

• Musi zaczynać się od https://, posiadać ważny certyfikat i działać na porcie 443.
• Zawiera tylko nazwę strony i ścieżkę, bez nazwy użytkownika i hasła wewnątrz.
• Nazwa strony musi być publiczna i dostępna z Internetu.