Notifications au logiciel de gestion

Si vous utilisez un logiciel de gestion, ou un outil d'automatisation comme Zapier ou Make, vous pouvez être informé en temps réel dès qu'une réservation est créée, modifiée ou annulée, ainsi que lors de l'arrivée et du départ des voyageurs. Fini la saisie manuelle des dates.

À quoi servent ces notifications

Chaque fois qu'une réservation change de statut, Roraima envoie un court message à l'adresse que vous avez indiquée. Votre logiciel de gestion le reçoit et se met à jour automatiquement : il marque le logement comme occupé, prépare le ménage, écrit au voyageur et met à jour vos comptes. Tout ce que vous faisiez auparavant en consultant votre tableau de bord et en recopiant les données, c'est désormais votre logiciel qui s'en charge.

Comment les activer

Dans votre tableau de bord, ouvrez le menu Connexions et choisissez Notifications au logiciel de gestion. Collez-y l'adresse fournie par votre logiciel (généralement disponible dans ses paramètres, sous la rubrique dédiée aux connexions entrantes), donnez-lui un nom pour la reconnaître facilement et choisissez les notifications à envoyer : Réservation confirmée, Réservation modifiée, Réservation annulée, Arrivée enregistrée, Départ enregistré, Voyageur non présenté. Lorsque vous enregistrez, Roraima vérifie immédiatement que l'adresse est valide et accessible depuis Internet. Vous pouvez connecter jusqu'à cinq adresses, par exemple votre logiciel de gestion et un tableur géré par Zapier.

Chaque adresse possède sa propre clé de signature, que vous pouvez consulter à tout moment : ouvrez «Clé de signature» sous l'adresse et cliquez sur «Montrer», la clé s'affiche sur une page à part. Elle doit être transmise à votre logiciel, ou à la personne qui le configure : elle lui permet de vérifier que le message provient bien de Roraima. Considérez-la comme un mot de passe. Si vous pensez qu'elle a été compromise, cliquez sur «Créer une nouvelle clé» : l'ancienne cessera immédiatement de fonctionner, et la nouvelle, que vous voyez à nouveau avec «Montrer», devra être saisie dans votre logiciel.

Si vous avez confié votre logement à un gestionnaire avec une délégation active, il peut également connecter son propre logiciel et recevoir les notifications des réservations qu'il gère pour vous.

Les données du voyageur, uniquement si nécessaire

Par défaut, le message contient tout ce qui est nécessaire pour organiser le séjour : logement ou espace, dates, horaires, nombre de personnes, montant et statut de la réservation. Le nom, l'e-mail et le téléphone du voyageur ne sont pas inclus.

Si votre logiciel en a besoin, par exemple pour envoyer un message de bienvenue ou remplir la fiche client, cochez la case Inclure le nom, l’e-mail et le téléphone du voyageur pour cette adresse. Elle est désactivée par défaut : c'est vous qui l'activez, adresse par adresse, uniquement là où c'est vraiment utile.

Faire un test avant de commencer

À côté de chaque adresse active se trouve le bouton Envoyer un test. Roraima envoie immédiatement un message d'exemple, avec le même format qu'un vrai mais avec des données fictives. Le résultat s'affiche instantanément en haut de la page et dans la liste des derniers envois. Aucune réservation n'est impactée, et vous pouvez répéter le test autant de fois que nécessaire pendant la configuration.

Si le logiciel ne répond pas

Cela peut arriver : le serveur du logiciel est en maintenance, la connexion est interrompue, ou un réglage a été modifié. Roraima ne perd pas la notification et réessaie automatiquement, à des intervalles de plus en plus longs, pendant près de deux jours.

Cependant, si l'adresse ne répond qu'avec des erreurs pendant vingt-quatre heures consécutives, Roraima la suspend et vous envoie un e-mail pour vous prévenir. Lorsque le logiciel est à nouveau accessible, cliquez sur Réactiver à côté de l'adresse pour relancer les notifications. Le même bouton est utilisé après «Mettre en pause», que vous pouvez activer si vous souhaitez interrompre les envois temporairement, par exemple lors d'un changement de logiciel : les notifications des réservations modifiées pendant la pause ne sont pas envoyées, et tout reprend dès la réactivation.

Dans la liste Derniers envois, vous trouverez les vingt dernières notifications de toutes vos adresses, avec la date, le type d'avis, la réservation, l'adresse et le résultat : Remise, En attente d’une nouvelle tentative ou Non remise (avec le motif de l'échec).

Pour le développeur de la connexion

Chaque notification est une requête POST avec un corps JSON, un événement par requête, envoyée à l'adresse enregistrée par le propriétaire. Voici les en-têtes envoyés à chaque fois :

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 correspond à la valeur du champ id dans le corps, et Roraima-Event-Type à celle du champ type : vous pouvez décider quoi faire d'une notification avant même d'en lire le contenu.

Les événements

• booking.confirmed : une réservation est confirmée. Cela inclut celles provenant d'autres canaux connectés et celles saisies manuellement. Elle peut aussi arriver pour une réservation que votre système connaît déjà : lorsque le canal d'origine la rend de nouveau valide après l'avoir annulée, ou lorsqu'elle redevient valide après que le propriétaire a résolu un chevauchement avec une autre réservation. Dans ces cas, previous_status indique de quel statut elle revient : mettez à jour la réservation ayant le même booking.id, sans en créer une nouvelle.
• booking.modified : les dates, l'horaire ou le nombre de personnes ont changé. Le champ changes détaille les modifications.
• booking.cancelled : la réservation est annulée. cancelled_by indique si l'annulation provient de Roraima ou du canal d'origine.
• booking.checked_in : le voyageur est arrivé.
• booking.checked_out : le voyageur est reparti. Si le départ a été clôturé automatiquement à l'échéance, closed_automatically est réglé sur true.
• booking.no_show : le voyageur ne s'est pas présenté.

Le propriétaire choisit dans le tableau de bord quels événements envoyer à chaque adresse : si un type ne vous est pas utile, vous pouvez lui demander de le désactiver.

Un exemple complet

Le corps est envoyé de manière compacte, sur une seule ligne ; il est ici mis en forme pour une meilleure lisibilité. Les champs peuvent évoluer, mais ceux présents ne changeront ni de nom ni de signification tant que la api_version reste la même : ignorez les champs que vous ne connaissez pas.

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

Pour un booking.modified, changes contient uniquement les champs modifiés, avec l'ancienne et la nouvelle valeur :

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

Signification des champs de booking :

• status et previous_status : le statut après et avant l'événement. Dans un booking.modified, où le statut ne change pas, les deux sont identiques. previous_status vaut null uniquement pour une réservation créée directement en statut confirmé, saisie manuellement ou provenant d'un calendrier connecté.
• source : l'origine de la réservation. native pour la boutique Roraima, manual pour une saisie manuelle, ical_airbnb, ical_booking_com, ical_vrbo ou ical_generic pour un calendrier connecté.
• external_id : pour les réservations provenant d'un calendrier connecté, l'identifiant attribué par ce calendrier ; sinon null.
• check_in et check_out : les dates au format AAAA-MM-JJ. Pour les réservations à l'heure, booking_mode vaut hourly et time_slot contient l'horaire, par exemple {"from": "10:00", "to": "12:00"}.
• guests : le nombre de personnes déclarées.
• amount et currency : le montant sous forme de texte avec deux décimales et la devise ; les deux valent null si la réservation n'a pas de montant, ce qui est fréquent pour les réservations provenant de calendriers.
• actor : l'auteur de l'événement. guest, buyer, vendor (le propriétaire), manager (un gestionnaire délégué), admin, channel (un calendrier connecté) ou system.
• guest : nom, e-mail et téléphone du voyageur, uniquement si le propriétaire a activé l'option pour cette adresse ; sinon null.

Vérification de la signature

Chaque requête est signée avec la clé de signature de l'adresse, commençant par whsec_. L'en-tête Roraima-Signature suit le format t=<timestamp>,v1=<hex>, où v1 est le HMAC-SHA256 de t, un point et le corps de la requête, calculé avec la clé complète (préfixe inclus).

Trois précautions sont essentielles : calculez la signature sur le corps brut tel qu'il a été reçu, et jamais sur un JSON réinterprété ; comparez les deux signatures en temps constant ; rejetez la requête si t diffère de plus de 300 secondes de votre horloge. En 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);

En Node, sans bibliothèques externes :

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

Doublons et ordre d'arrivée

Une même notification peut arriver plusieurs fois, par exemple si votre réponse est perdue et que Roraima réessaie. Enregistrez l'id de chaque événement déjà traité et ignorez ceux qui se répètent.

Avec les tentatives de réenvoi, deux notifications pour la même réservation peuvent arriver dans un ordre différent de celui des événements réels : un booking.modified avant un booking.confirmed. Utilisez booking.sequence pour remettre les choses dans l'ordre : c'est un numéro qui augmente à chaque notification pour une réservation donnée vers une adresse donnée. Conservez le dernier numéro enregistré pour chaque réservation et ignorez les notifications avec un numéro inférieur. Les numéros ne sont pas forcément consécutifs : il peut y avoir des sauts.

Réponses et tentatives

Une notification est considérée comme remise lorsque votre adresse répond avec un code 2xx en moins de 5 secondes. Le contenu de la réponse n'est pas analysé. Tout autre résultat compte comme une tentative échouée, y compris une redirection vers une autre adresse (3xx) : enregistrez l'adresse définitive dans le tableau de bord.

Après un échec, Roraima réessaie après 1 minute, puis 5, 15, 1 heure, 3, 6, 12 et 24 heures. Si la dernière tentative échoue, la notification est marquée comme non remise. Si l'adresse ne répond qu'avec des erreurs pendant 24 heures, elle est suspendue, les notifications en attente sont stoppées et le propriétaire reçoit un e-mail ; la reprise s'effectue lorsque le propriétaire clique sur «Réactiver». Les notifications créées pendant qu'une adresse est suspendue ou mise en pause ne sont pas envoyées.

Pour respecter le délai de 5 secondes, la méthode la plus sûre est de répondre immédiatement après avoir vérifié la signature et enregistré l'événement, puis d'effectuer le traitement long en arrière-plan.

La notification de test

Le bouton «Envoyer un test», disponible sur les adresses actives, envoie un booking.confirmed au format réel, signé de la même manière, avec "test": true, booking.id égal à 0 et des données fictives. Si les données voyageur sont activées, elles sont également fictives. Le test n'est effectué qu'une seule fois et le résultat apparaît immédiatement. Vérifiez le champ test avant de créer quoi que ce soit dans votre système.

Reconnaître ce qui provient de votre propre logiciel

Si votre logiciel envoie déjà ses réservations à Roraima via un calendrier connecté, les notifications de ces réservations lui reviendront. Pour les identifier, utilisez source et external_id : external_id est l'identifiant que votre calendrier a attribué à la réservation, celui que vous connaissez déjà.

Exigences pour l'adresse

Le tableau de bord les vérifie lors de l'enregistrement, et Roraima les contrôle à chaque envoi :

• Doit commencer par https://, avec un certificat valide, sur le port 443.
• Contient uniquement le nom du site et le chemin, sans nom d'utilisateur ni mot de passe.
• Le nom du site doit être public et accessible depuis Internet.