Avvisi ai gestionali

Se lavori con un gestionale, o con uno strumento di automazione come Zapier o Make, puoi fargli sapere nel momento stesso in cui succede che una prenotazione è nata, è cambiata o è stata annullata, e quando l'ospite arriva e riparte. Niente più date ricopiate a mano.

A cosa servono gli avvisi

Ogni volta che una prenotazione cambia stato, Roraima manda un breve messaggio all'indirizzo che hai indicato tu. Il tuo gestionale lo riceve e si aggiorna da solo: segna la camera occupata, prepara le pulizie, scrive all'ospite, aggiorna i conti. Tutto quello che prima facevi guardando il pannello e ricopiando, adesso lo fa il programma che usi già.

Dove si accendono

Nel pannello apri il menu Collegamenti e scegli Avvisi ai gestionali. Lì incolli l'indirizzo che ti ha dato il gestionale (di solito lo trovi nelle sue impostazioni, alla voce dedicata ai collegamenti in entrata), gli dai un nome che ti aiuti a riconoscerlo e scegli quali avvisi mandargli: Prenotazione confermata, Prenotazione modificata, Prenotazione annullata, Arrivo registrato, Partenza registrata, Ospite non presentato. Quando salvi, Roraima controlla subito che l'indirizzo sia scritto bene e raggiungibile da Internet. Puoi collegare fino a cinque indirizzi, per esempio il gestionale e un foglio di calcolo tenuto da Zapier.

Ogni indirizzo ha la sua chiave di firma, che vedi quando vuoi: apri «Chiave di firma» sotto l'indirizzo e premi «Mostra», e la chiave compare in una pagina a sé. Va consegnata al gestionale, o a chi lo configura: serve a lui per riconoscere che il messaggio arriva davvero da Roraima. Trattala come una password. Se pensi che sia finita in mani sbagliate, premi «Crea una nuova chiave»: quella vecchia smette subito di funzionare, e la nuova, che vedi di nuovo con «Mostra», va inserita nel gestionale.

Se hai affidato la casa a un gestore con una delega attiva, anche lui può collegare il proprio gestionale e ricevere gli avvisi delle prenotazioni che segue per te.

I dati dell'ospite, solo se servono

Di partenza il messaggio contiene tutto ciò che serve per organizzare il soggiorno: alloggio o spazio, date, orario, numero di persone, importo e stato della prenotazione. Nome, email e telefono dell'ospite restano fuori.

Se il tuo gestionale ne ha bisogno, per esempio per mandare il messaggio di benvenuto o per compilare la scheda dell'ospite, accendi la casella Includi nome, email e telefono dell’ospite su quell'indirizzo. Nasce spenta di proposito: la accendi tu, indirizzo per indirizzo, solo dove ti serve davvero.

Una prova prima di cominciare

Accanto a ogni indirizzo attivo c'è il pulsante Invia una prova. Roraima manda subito un messaggio d'esempio, con la stessa forma di quelli veri ma con dati inventati, e l'esito compare sul momento in cima alla pagina e nell'elenco degli ultimi invii. Nessuna prenotazione viene toccata, e puoi ripetere la prova tutte le volte che vuoi mentre sistemi il collegamento.

Se il gestionale non risponde

Capita: il server del gestionale è in manutenzione, la connessione salta, qualcuno ha cambiato un'impostazione. Roraima non perde l'avviso e ci riprova da sola, a intervalli sempre più lunghi, da un minuto fino a un giorno intero, per quasi due giorni.

Se però per ventiquattro ore di fila quell'indirizzo risponde solo con errori, Roraima lo sospende e ti scrive un'email per avvisarti. Quando il gestionale torna raggiungibile, premi Riattiva accanto all'indirizzo e gli avvisi ripartono. Lo stesso pulsante serve dopo «Metti in pausa», che usi quando vuoi fermare gli invii per un po', per esempio mentre cambi gestionale: gli avvisi delle prenotazioni che cambiano durante la pausa restano fuori, e tutto riprende dal momento in cui riattivi.

Nell'elenco Ultimi invii trovi gli ultimi venti avvisi di tutti i tuoi indirizzi, con data, avviso, prenotazione, indirizzo ed esito: Consegnato, In attesa di un nuovo tentativo oppure Non consegnato, e in quest'ultimo caso anche il motivo.

Per chi costruisce il collegamento

Ogni avviso è una richiesta POST con un corpo JSON, un evento per richiesta, mandata all'indirizzo registrato dal proprietario. Queste sono le intestazioni che arrivano ogni volta:

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 è lo stesso valore del campo id nel corpo, e Roraima-Event-Type è lo stesso del campo type: puoi decidere cosa fare di un avviso anche prima di leggerne il corpo.

Gli eventi

• booking.confirmed: una prenotazione è confermata. Vale anche per quelle arrivate dagli altri canali collegati e per quelle inserite a mano. Può arrivare anche per una prenotazione che il tuo sistema conosce già: quando il canale di provenienza la rende di nuovo valida dopo averla annullata, oppure quando torna valida dopo che il proprietario ha risolto una sovrapposizione con un'altra prenotazione. In quei casi previous_status dice da quale stato torna: aggiorna la prenotazione con lo stesso booking.id, senza crearne una nuova.
• booking.modified: sono cambiate le date, l'orario o il numero di persone. Il campo changes dice cosa.
• booking.cancelled: la prenotazione è annullata. cancelled_by dice se l'annullamento è partito da Roraima o dal canale di provenienza.
• booking.checked_in: l'ospite è arrivato.
• booking.checked_out: l'ospite è ripartito. Se la partenza è stata chiusa d'ufficio alla scadenza, closed_automatically vale true.
• booking.no_show: l'ospite non si è presentato.

Il proprietario sceglie nel pannello quali eventi mandare a ogni indirizzo: se un tipo non ti serve, puoi chiedergli di lasciarlo spento.

Un esempio completo

Il corpo arriva compatto, su una riga sola; qui è impaginato per leggerlo meglio. I campi possono crescere nel tempo, ma quelli presenti non cambiano nome né significato finché resta la stessa api_version: ignora quelli che non conosci.

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

Per un booking.modified, changes contiene solo i campi cambiati, ciascuno col valore di prima e quello di adesso:

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

Il significato dei campi di booking:

• status e previous_status: lo stato dopo l'evento e quello di prima. In un booking.modified, dove lo stato non cambia, i due coincidono. previous_status vale null solo per una prenotazione nata già confermata, inserita a mano o arrivata da un calendario collegato.
• source: da dove è arrivata la prenotazione. native dal negozio Roraima, manual inserita a mano, ical_airbnb, ical_booking_com, ical_vrbo o ical_generic da un calendario collegato.
• external_id: per le prenotazioni arrivate da un calendario collegato, l'identificativo che le ha dato quel calendario; altrimenti null.
• check_in e check_out: le date, nella forma AAAA-MM-GG. Per le prenotazioni a ore, booking_mode vale hourly e time_slot porta l'orario, per esempio {"from": "10:00", "to": "12:00"}.
• guests: le persone dichiarate per il soggiorno.
• amount e currency: l'importo come testo con due decimali e la valuta; entrambi null quando la prenotazione non ha un importo, come spesso accade per quelle arrivate dai calendari.
• actor: chi ha causato l'evento. guest, buyer, vendor (il proprietario), manager (un gestore con delega), admin, channel (un calendario collegato) oppure system.
• guest: nome, email e telefono dell'ospite, solo se il proprietario ha acceso la casella su quell'indirizzo; altrimenti null.

Verificare la firma

Ogni richiesta è firmata con la chiave di firma dell'indirizzo, quella che comincia con whsec_. L'intestazione Roraima-Signature ha la forma t=<timestamp>,v1=<hex>, dove v1 è l'HMAC-SHA256 di t, un punto e il corpo della richiesta, calcolato con la chiave intera, prefisso compreso.

Tre accortezze fanno la differenza: calcola la firma sul corpo grezzo, così come è arrivato, e mai su un JSON riletto e riscritto; confronta le due firme a tempo costante; scarta la richiesta se t dista più di 300 secondi dal tuo orologio. 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, senza librerie esterne:

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

Doppioni e ordine di arrivo

Lo stesso avviso può arrivare più di una volta, per esempio quando la tua risposta si perde per strada e Roraima riprova. Registra l'id di ogni evento che hai già trattato e ignora quelli che ritornano.

Con i ritentativi, inoltre, due avvisi della stessa prenotazione possono arrivare in ordine diverso da quello in cui sono successi: un booking.modified prima del suo booking.confirmed. Per rimettere le cose in fila c'è booking.sequence, un numero che cresce a ogni avviso della stessa prenotazione verso lo stesso indirizzo. Tieni l'ultimo che hai registrato per ogni prenotazione e scarta gli avvisi con un numero più basso. I numeri non sono consecutivi: fra un avviso e l'altro possono saltarne molti.

Risposte e ritentativi

Un avviso è consegnato quando il tuo indirizzo risponde con un codice 2xx entro 5 secondi. Il contenuto della risposta non viene letto. Qualunque altro esito conta come un tentativo fallito, compreso un rimando verso un altro indirizzo (3xx): registra l'indirizzo definitivo nel pannello.

Dopo un tentativo fallito Roraima riprova dopo 1 minuto, poi dopo 5 minuti, 15 minuti, 1 ora, 3 ore, 6 ore, 12 ore e 24 ore. Se anche l'ultimo tentativo fallisce, quell'avviso si chiude come non consegnato. Se l'indirizzo risponde solo con errori per 24 ore di fila, viene sospeso, gli avvisi in attesa si fermano e il proprietario riceve un'email; riparte quando il proprietario preme «Riattiva». Gli avvisi nati mentre un indirizzo è sospeso o messo in pausa dal proprietario non vengono inviati.

Per stare nei 5 secondi, la strada più sicura è rispondere subito dopo aver controllato la firma e registrato l'evento, e fare il lavoro lungo in un secondo momento.

L'avviso di prova

Il pulsante «Invia una prova», disponibile sugli indirizzi attivi, manda un booking.confirmed con la stessa forma di quelli veri, firmato allo stesso modo, con "test": true, booking.id uguale a 0 e dati inventati. Se sull'indirizzo sono accesi i dati dell'ospite, anche quelli sono inventati. La prova si tenta una volta sola e il risultato compare subito nel pannello. Controlla test prima di creare qualcosa nel tuo sistema.

Riconoscere ciò che arriva dal tuo stesso gestionale

Se il tuo gestionale manda già le sue prenotazioni a Roraima attraverso un calendario collegato, gli avvisi di quelle prenotazioni tornano indietro anche a lui. Per riconoscerle usa source ed external_id: external_id è l'identificativo che il tuo calendario ha dato alla prenotazione, lo stesso che conosci già.

Requisiti dell'indirizzo

Il pannello li controlla già al salvataggio, e Roraima li ricontrolla a ogni invio:

• Comincia con https://, con un certificato valido, sulla porta 443.
• Contiene solo il nome del sito e il percorso, senza nome utente e password al suo interno.
• Il nome del sito è pubblico e raggiungibile da Internet.