Notifications to management software

If you work with management software, or with an automation tool such as Zapier or Make, you can let it know the moment a booking is created, changed or cancelled, and when the guest arrives and leaves. No more copying dates by hand.

What the alerts are for

Every time a booking changes status, Roraima sends a short message to the address you have given it. Your software receives it and updates itself: it marks the room as taken, schedules the cleaning, writes to the guest, updates the accounts. Everything you used to do by looking at the panel and copying things across is now done by the program you already use.

Where to switch them on

In the panel, open the Connections menu and choose Notifications to management software. There you paste the address your software gave you (you usually find it in its settings, in the section about incoming connections), give it a name that helps you recognise it and choose which alerts to send: Booking confirmed, Booking changed, Booking cancelled, Arrival recorded, Departure recorded, Guest did not show up. When you save, Roraima immediately checks that the address is well formed and reachable from the Internet. You can connect up to five addresses, for example your management software and a spreadsheet kept up to date by Zapier.

Each address has its own signing key, which you can see whenever you like: open «Signing key» under the address and press «Show», and the key appears on a page of its own. Hand it to your software, or to whoever sets it up: it is how the software recognises that a message really comes from Roraima. Treat it like a password. If you think it has ended up in the wrong hands, press «Create a new key»: the old one stops working at once, and the new one, which you again see with «Show», must be entered in your software.

If you have entrusted your property to a manager with an active mandate, they can also connect their own software and receive the alerts for the bookings they look after for you.

Guest details, only when needed

By default the message contains everything needed to organise the stay: accommodation or space, dates, time, number of guests, amount and booking status. The guest's name, email and phone number stay out.

If your software needs them, for example to send the welcome message or to fill in the guest record, tick the box Include the guest’s name, email and phone number on that address. It starts unticked on purpose: you switch it on yourself, address by address, only where you really need it.

A test before you start

Next to each active address there is a Send a test button. Roraima immediately sends a sample message, shaped exactly like the real ones but with made-up data, and the outcome appears on the spot at the top of the page and in the list of latest deliveries. No booking is touched, and you can repeat the test as often as you like while you set up the connection.

If your software does not answer

It happens: the software's server is under maintenance, the connection drops, someone has changed a setting. Roraima keeps the alert and tries again on its own, at longer and longer intervals, from one minute up to a whole day, for almost two days.

If, however, that address answers only with errors for twenty-four hours in a row, Roraima suspends it and sends you an email to let you know. When your software is reachable again, press Resume next to the address and the alerts start again. The same button is used after «Pause», which you use when you want to stop the deliveries for a while, for example while you change software: alerts for bookings that change during the pause are left out, and everything starts again from the moment you resume.

In the Latest notifications sent list you will find the last twenty alerts for all your addresses, with date, alert, booking, address and outcome: Delivered, Waiting for a new attempt or Not delivered, and in that last case the reason as well.

For whoever builds the connection

Each alert is a POST request with a JSON body, one event per request, sent to the address registered by the owner. These are the headers that arrive every time:

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 is the same value as the id field in the body, and Roraima-Event-Type is the same as the type field: you can decide what to do with an alert even before reading its body.

The events

• booking.confirmed: a booking is confirmed. This also covers bookings coming from the other connected channels and those entered by hand. It can also arrive for a booking your system already knows: when the channel it came from makes it valid again after cancelling it, or when it becomes valid again after the owner has resolved an overlap with another booking. In those cases previous_status tells you which status it is coming back from: update the booking with the same booking.id instead of creating a new one.
• booking.modified: the dates, the time or the number of guests have changed. The changes field says what.
• booking.cancelled: the booking is cancelled. cancelled_by says whether the cancellation started on Roraima or on the channel the booking came from.
• booking.checked_in: the guest has arrived.
• booking.checked_out: the guest has left. If the departure was closed automatically when the stay ended, closed_automatically is true.
• booking.no_show: the guest did not turn up.

The owner chooses in the panel which events to send to each address: if you do not need a type, you can ask them to leave it off.

A complete example

The body arrives compact, on a single line; here it is laid out to make it easier to read. Fields may be added over time, but the existing ones keep their name and meaning for as long as the api_version stays the same: ignore the ones you do not know.

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

For a booking.modified, changes contains only the fields that changed, each with its previous value and its current one:

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

What the booking fields mean:

• status and previous_status: the status after the event and the one before it. In a booking.modified, where the status does not change, the two are the same. previous_status is null only for a booking that was born already confirmed, entered by hand or coming from a connected calendar.
• source: where the booking came from. native from the Roraima shop, manual entered by hand, ical_airbnb, ical_booking_com, ical_vrbo or ical_generic from a connected calendar.
• external_id: for bookings coming from a connected calendar, the identifier that calendar gave them; otherwise null.
• check_in and check_out: the dates, in the form YYYY-MM-DD. For hourly bookings, booking_mode is hourly and time_slot carries the time, for example {"from": "10:00", "to": "12:00"}.
• guests: the number of people declared for the stay.
• amount and currency: the amount as a string with two decimals, and the currency; both null when the booking has no amount, as is often the case for those coming from calendars.
• actor: who caused the event. guest, buyer, vendor (the owner), manager (a manager with a mandate), admin, channel (a connected calendar) or system.
• guest: the guest's name, email and phone number, only if the owner has ticked the box on that address; otherwise null.

Verifying the signature

Every request is signed with the address's signing key, the one starting with whsec_. The Roraima-Signature header has the form t=<timestamp>,v1=<hex>, where v1 is the HMAC-SHA256 of t, a dot and the request body, computed with the whole key, prefix included.

Three precautions make the difference: compute the signature on the raw body, exactly as it arrived, never on JSON that has been parsed and written out again; compare the two signatures in constant time; reject the request if t is more than 300 seconds away from your clock. 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, with no external libraries:

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

Duplicates and order of arrival

The same alert can arrive more than once, for example when your reply gets lost on the way and Roraima tries again. Record the id of every event you have already handled and ignore the ones that come back.

Because of retries, two alerts for the same booking can also arrive in a different order from the one in which they happened: a booking.modified before its booking.confirmed. To put things back in order there is booking.sequence, a number that grows with every alert for the same booking sent to the same address. Keep the last one you recorded for each booking and discard alerts with a lower number. The numbers are not consecutive: many may be skipped between one alert and the next.

Responses and retries

An alert is delivered when your address answers with a 2xx code within 5 seconds. The content of the response is not read. Any other outcome counts as a failed attempt, including a redirect to another address (3xx): register the final address in the panel.

After a failed attempt Roraima tries again after 1 minute, then after 5 minutes, 15 minutes, 1 hour, 3 hours, 6 hours, 12 hours and 24 hours. If the last attempt fails too, that alert is closed as not delivered. If the address answers only with errors for 24 hours in a row, it is suspended, the pending alerts stop and the owner receives an email; it starts again when the owner presses «Resume». Alerts created while an address is suspended or paused by the owner are not sent.

To stay within the 5 seconds, the safest way is to answer as soon as you have checked the signature and recorded the event, and to do the long work afterwards.

The test alert

The «Send a test» button, available on active addresses, sends a booking.confirmed shaped exactly like the real ones, signed the same way, with "test": true, booking.id equal to 0 and made-up data. If guest details are switched on for the address, those are made up too. The test is attempted only once and the result appears straight away in the panel. Check test before creating anything in your system.

Recognising what comes from your own software

If your software already sends its bookings to Roraima through a connected calendar, the alerts for those bookings come back to it too. To recognise them, use source and external_id: external_id is the identifier your calendar gave the booking, the one you already know.

Address requirements

The panel checks them as soon as you save, and Roraima checks them again at every delivery:

• It starts with https://, with a valid certificate, on port 443.
• It contains only the site name and the path, with no username and password inside it.
• The site name is public and reachable from the Internet.