Avisos al programa de gestión

Si trabajas con un programa de gestión, o con una herramienta de automatización como Zapier o Make, puedes recibir un aviso en el mismo instante en que se crea, modifica o cancela una reserva, así como cuando el huésped llega o se marcha. Olvídate de copiar fechas a mano.

Para qué sirven los avisos

Cada vez que una reserva cambia de estado, Roraima envía un breve mensaje a la dirección que hayas indicado. Tu programa de gestión lo recibe y se actualiza solo: marca la habitación como ocupada, prepara la limpieza, escribe al huésped y actualiza las cuentas. Todo lo que antes hacías mirando el panel y copiando datos, ahora lo hace el programa que ya usas.

Dónde se activan

En el panel, abre el menú Conexiones y elige Avisos al programa de gestión. Ahí pegas la dirección que te haya proporcionado tu programa (normalmente se encuentra en sus ajustes, en el apartado dedicado a las conexiones entrantes), le das un nombre para identificarla y eliges qué avisos quieres enviar: Reserva confirmada, Reserva modificada, Reserva cancelada, Llegada registrada, Salida registrada, El huésped no se presentó. Al guardar, Roraima comprueba al instante que la dirección sea correcta y accesible desde Internet. Puedes conectar hasta cinco direcciones, por ejemplo, tu programa de gestión y una hoja de cálculo gestionada por Zapier.

Cada dirección tiene su propia clave de firma, que puedes ver cuando quieras: abre «Clave de firma» debajo de la dirección y pulsa «Mostrar», y la clave aparece en una página aparte. Debes entregársela al programa de gestión, o a quien lo configure: le sirve para reconocer que el mensaje proviene realmente de Roraima. Trátala como una contraseña. Si crees que ha caído en manos equivocadas, pulsa «Crear una clave nueva»: la antigua dejará de funcionar inmediatamente y deberás introducir la nueva, que vuelves a ver con «Mostrar», en el programa de gestión.

Si has confiado tu propiedad a un gestor con una delegación activa, él también podrá conectar su propio programa de gestión y recibir los avisos de las reservas que gestiona por ti.

Los datos del huésped, solo si son necesarios

Por defecto, el mensaje contiene todo lo necesario para organizar la estancia: alojamiento o espacio, fechas, horario, número de personas, importe y estado de la reserva. El nombre, email y teléfono del huésped no se incluyen.

Si tu programa de gestión los necesita, por ejemplo para enviar el mensaje de bienvenida o rellenar la ficha del huésped, activa la casilla Incluir nombre, email y teléfono del huésped en esa dirección. Viene desactivada por defecto: tú decides, dirección por dirección, cuándo activarla si realmente te hace falta.

Una prueba antes de empezar

Junto a cada dirección activa hay un botón Enviar una prueba. Roraima envía al momento un mensaje de ejemplo, con el mismo formato que los reales pero con datos ficticios; el resultado aparece al instante en la parte superior de la página y en la lista de los últimos envíos. No se toca ninguna reserva y puedes repetir la prueba tantas veces como quieras mientras configuras la conexión.

Si el programa de gestión no responde

Puede ocurrir: el servidor del programa está en mantenimiento, la conexión falla o alguien ha cambiado un ajuste. Roraima no pierde el aviso y vuelve a intentarlo automáticamente, en intervalos cada vez más largos, desde un minuto hasta un día entero, durante casi dos días.

Sin embargo, si durante veinticuatro horas seguidas esa dirección solo responde con errores, Roraima la suspende y te envía un email para avisarte. Cuando el programa de gestión vuelva a estar operativo, pulsa Reactivar junto a la dirección y los avisos se reanudarán. El mismo botón sirve después de «Pausar», que puedes usar cuando quieras detener los envíos durante un tiempo, por ejemplo mientras cambias de programa de gestión: los avisos de las reservas que cambien durante la pausa no se enviarán, y todo se retomará desde el momento en que vuelvas a activar.

En la lista Últimos envíos verás los últimos veinte avisos de todas tus direcciones, con fecha, tipo de aviso, reserva, dirección y resultado: Entregado, A la espera de un nuevo intento o No entregado (en este último caso, indicando también el motivo).

Para quien desarrolla la conexión

Cada aviso es una solicitud POST con un cuerpo JSON, un evento por solicitud, enviada a la dirección registrada por el propietario. Estas son las cabeceras que llegan en cada ocasión:

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 es el mismo valor que el campo id en el cuerpo, y Roraima-Event-Type es el mismo que el campo type: puedes decidir qué hacer con un aviso incluso antes de leer su cuerpo.

Los eventos

• booking.confirmed: una reserva ha sido confirmada. También es válido para las que llegan desde otros canales conectados y las introducidas manualmente. También puede llegar para una reserva que tu sistema ya conoce: cuando el canal de procedencia la vuelve a dar por válida después de haberla cancelado, o cuando vuelve a ser válida después de que el propietario haya resuelto una superposición con otra reserva. En esos casos, previous_status indica de qué estado vuelve: actualiza la reserva con el mismo booking.id, sin crear una nueva.
• booking.modified: han cambiado las fechas, el horario o el número de personas. El campo changes detalla qué.
• booking.cancelled: la reserva ha sido cancelada. cancelled_by indica si la cancelación se originó en Roraima o en el canal de procedencia.
• booking.checked_in: el huésped ha llegado.
• booking.checked_out: el huésped se ha marchado. Si la salida se cerró de oficio al finalizar, closed_automatically será true.
• booking.no_show: el huésped no se ha presentado.

El propietario elige en el panel qué eventos enviar a cada dirección: si un tipo no te sirve, puedes pedirle que lo deje desactivado.

Un ejemplo completo

El cuerpo llega compacto, en una sola línea; aquí está maquetado para facilitar su lectura. Los campos pueden crecer con el tiempo, pero los existentes no cambian de nombre ni de significado mientras se mantenga la misma api_version: ignora los que no conozcas.

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

Para un booking.modified, changes contiene solo los campos modificados, cada uno con el valor anterior y el actual:

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

El significado de los campos de booking:

• status y previous_status: el estado después del evento y el anterior. En un booking.modified, donde el estado no cambia, ambos coinciden. previous_status es null solo para una reserva nacida ya confirmada, introducida manualmente o llegada desde un calendario conectado.
• source: origen de la reserva. native desde la tienda Roraima, manual introducida manualmente, ical_airbnb, ical_booking_com, ical_vrbo o ical_generic desde un calendario conectado.
• external_id: para las reservas llegadas desde un calendario conectado, el identificador que le asignó dicho calendario; de lo contrario, null.
• check_in y check_out: las fechas, en formato AAAA-MM-DD. Para las reservas por horas, booking_mode es hourly y time_slot indica el horario, por ejemplo {"from": "10:00", "to": "12:00"}.
• guests: las personas declaradas para la estancia.
• amount y currency: el importe como texto con dos decimales y la divisa; ambos null cuando la reserva no tiene importe, como suele ocurrir con las llegadas desde calendarios.
• actor: quién causó el evento. guest, buyer, vendor (el propietario), manager (un gestor con delegación), admin, channel (un calendario conectado) o system.
• guest: nombre, email y teléfono del huésped, solo si el propietario ha activado la casilla en esa dirección; de lo contrario, null.

Verificar la firma

Cada solicitud está firmada con la clave de firma de la dirección, la que comienza con whsec_. La cabecera Roraima-Signature tiene el formato t=<timestamp>,v1=<hex>, donde v1 es el HMAC-SHA256 de t, un punto y el cuerpo de la solicitud, calculado con la clave completa, incluyendo el prefijo.

Tres precauciones marcan la diferencia: calcula la firma sobre el cuerpo original, tal cual ha llegado, y nunca sobre un JSON leído y reescrito; compara ambas firmas a tiempo constante; descarta la solicitud si t dista más de 300 segundos de tu reloj. 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, sin librerías externas:

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

Duplicados y orden de llegada

El mismo aviso puede llegar más de una vez, por ejemplo cuando tu respuesta se pierde por el camino y Roraima vuelve a intentarlo. Registra el id de cada evento que ya hayas procesado e ignora los que vuelvan a aparecer.

Además, con los reintentos, dos avisos de la misma reserva pueden llegar en un orden distinto al que ocurrieron: un booking.modified antes de su booking.confirmed. Para poner las cosas en orden existe booking.sequence, un número que aumenta con cada aviso de la misma reserva hacia la misma dirección. Conserva el último que hayas registrado para cada reserva y descarta los avisos con un número inferior. Los números no son consecutivos: entre un aviso y otro pueden saltarse muchos.

Respuestas y reintentos

Un aviso se considera entregado cuando tu dirección responde con un código 2xx en menos de 5 segundos. El contenido de la respuesta no se lee. Cualquier otro resultado cuenta como un intento fallido, incluido un redireccionamiento hacia otra dirección (3xx): registra la dirección definitiva en el panel.

Tras un intento fallido, Roraima vuelve a probar después de 1 minuto, luego a los 5 minutos, 15 minutos, 1 hora, 3 horas, 6 horas, 12 horas y 24 horas. Si el último intento también falla, ese aviso se cierra como no entregado. Si la dirección solo responde con errores durante 24 horas seguidas, se suspende, los avisos pendientes se detienen y el propietario recibe un email; se reanuda cuando el propietario pulsa «Reactivar». Los avisos generados mientras una dirección está suspendida o pausada por el propietario no se envían.

Para cumplir con los 5 segundos, la forma más segura es responder inmediatamente después de comprobar la firma y registrar el evento, dejando el trabajo pesado para un segundo momento.

El aviso de prueba

El botón «Enviar una prueba», disponible en las direcciones activas, envía un booking.confirmed con el mismo formato que los reales, firmado de la misma manera, con "test": true, booking.id igual a 0 y datos ficticios. Si en la dirección están activados los datos del huésped, estos también serán ficticios. La prueba se intenta una sola vez y el resultado aparece inmediatamente en el panel. Comprueba test antes de crear nada en tu sistema.

Reconocer lo que llega desde tu propio programa de gestión

Si tu programa de gestión ya envía sus reservas a Roraima a través de un calendario conectado, los avisos de esas reservas también volverán a él. Para reconocerlas, utiliza source y external_id: external_id es el identificador que tu calendario asignó a la reserva, el mismo que ya conoces.

Requisitos de la dirección

El panel ya los comprueba al guardar, y Roraima los vuelve a verificar en cada envío:

• Debe comenzar con https://, con un certificado válido, en el puerto 443.
• Debe contener solo el nombre del sitio y la ruta, sin nombre de usuario ni contraseña en su interior.
• El nombre del sitio debe ser público y accesible desde Internet.