Webhooks — avisos en tiempo real

En vez de consultar la API cada rato, deja que R2 le avise a tu sistema en el momento en que ocurre un evento: una reserva creada, modificada o cancelada, un pago cobrado.

Un webhook es una URL de tu sistema que R2 llama con un POST cada vez que ocurre algo que te interesa. El dueño del negocio registra el endpoint desde su panel, elige qué eventos escuchar, y R2 empieza a avisar. Es la forma eficiente de mantenerte sincronizado: sin consultar en ciclo, sin retraso.

Eventos disponibles#

Cómo integrar, paso a paso#

Esta es la secuencia completa para mantener tu sistema al día con las reservas de un negocio, sin consultar la API en ciclo:

1. El dueño genera la API key desde su panel (Configuración → R2 Connect API) con el permiso read:reservations, y te la comparte. Se muestra una sola vez.
2. Carga inicial por la API de lectura: recorre GET /reservations paginando hasta que has_more sea false. Este paso se hace UNA vez; el webhook no reproduce el histórico anterior a su registro.
3. Expón un endpoint HTTPS que acepte POST con cuerpo JSON. Debe contestar 2xx en menos de 5 segundos: confirma primero, procesa después en segundo plano.
4. El dueño registra el endpoint y elige los eventos. Para hospedaje: reservation.created, reservation.updated y reservation.cancelled. Guarda el secreto de firma que aparece al registrarlo — solo se muestra esa vez.
5. Verifica la firma de cada POST antes de hacerle caso (procedimiento abajo). Un aviso sin firma válida se descarta: no vino de R2.
6. Deduplica por R2-Delivery-Id y descarta los eventos cuyo updated_at sea anterior al que ya guardaste para esa reserva.
7. Aplica el evento como estado, no como diferencia: cada aviso describe cómo quedó la reserva. Si necesitas el desglose completo (líneas, impuestos, pagos), pídelo con GET /reservations/{order_number}.

Forma del payload#

Cada aviso llega como JSON. Trae el tipo de evento, cuándo ocurrió, y un objeto data con los campos clave. Para el detalle completo, pide el recurso por la API con el order_number o el id.

{
  "event": "payment.succeeded",
  "occurred_at": "2026-07-16T10:20:14.907Z",
  "data": {
    "object": "payment",
    "id": "n47dk3mzq81ba5tv",
    "order_id": "p97cbaneya88az5ra",
    "order_number": "ORD-MRNCRMX2-3BAW",
    "amount": 2088,
    "currency": "MXN",
    "status": "succeeded",
    "method": "card",
    "succeeded_at": "2026-07-16T10:20:14.907Z"
  }
}

Los eventos de reserva traen la estancia completa. En una cancelación se agregan cancelled_at y cancellation_reason:

{
  "event": "reservation.updated",
  "occurred_at": "2026-08-14T18:03:22.114Z",
  "data": {
    "object": "reservation",
    "id": "p97cbaneya88az5ra",
    "order_number": "ORD-MRNCRMX2-3BAW",
    "type": "booking",
    "status": "confirmed",
    "channel": "booking_com",
    "guest_name": "María Fernández",
    "check_in": "2026-09-05",
    "check_out": "2026-09-08",
    "guests": { "adults": 2, "children": 0 },
    "currency": "MXN",
    "subtotal": 8275.86,
    "tax_total": 1324.14,
    "total": 9600,
    "created_at": "2026-08-01T15:41:09.522Z",
    "updated_at": "2026-08-14T18:03:22.114Z"
  }
}

Campos del payload de reserva#

Esto es todo lo que viaja en un reservation.created, reservation.updated o reservation.cancelled. Los importes van en la moneda del negocio, con decimales; las fechas de estancia en AAAA-MM-DD y las marcas de tiempo en ISO 8601 (UTC).

Encabezados de cada POST#

Verificar la firma (importante)#

Al registrar el webhook, el dueño recibe un secreto de firma (empieza con whsec_) que solo se muestra una vez. Con él verificas que cada aviso viene de R2 y no de un impostor. El procedimiento es idéntico al de Stripe:

1. Toma el encabezado R2-Signature y separa t (timestamp) y v1 (firma).
2. Construye la cadena firmada: {t}.{cuerpo_crudo} — el cuerpo EXACTO que recibiste, sin re-serializar.
3. Calcula HMAC-SHA256(secreto, cadena_firmada) en hexadecimal.
4. Compáralo con v1 usando comparación de tiempo constante.
5. Rechaza si no coincide, o si t tiene más de 5 minutos (protección anti-repetición).

// Node.js / Express — verificación del webhook
import crypto from "node:crypto";

const SECRET = process.env.R2_WEBHOOK_SECRET; // whsec_...

// OJO: necesitas el cuerpo CRUDO (raw), no el ya parseado.
app.post("/webhooks/r2", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("R2-Signature") || "";
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  const body = req.body.toString("utf8");

  // 1) Anti-repetición: rechaza timestamps viejos
  if (Math.abs(Date.now() / 1000 - t) > 300) return res.status(400).end();

  // 2) Recalcula la firma
  const expected = crypto.createHmac("sha256", SECRET)
    .update(`${t}.${body}`).digest("hex");

  // 3) Comparación de tiempo constante
  const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
  if (!ok) return res.status(400).end();

  // 4) Responde 2xx RÁPIDO y procesa después
  const evento = JSON.parse(body);
  encolarParaProcesar(evento);       // no bloquees la respuesta
  res.status(200).end();
});

# Python / Flask — verificación del webhook
import hmac, hashlib, time, os
from flask import request, abort

SECRET = os.environ["R2_WEBHOOK_SECRET"].encode()

@app.post("/webhooks/r2")
def r2_webhook():
    header = dict(p.split("=") for p in request.headers.get("R2-Signature", "").split(","))
    t = int(header.get("t", "0"))
    body = request.get_data()  # crudo, en bytes

    if abs(time.time() - t) > 300:
        abort(400)  # anti-repetición

    expected = hmac.new(SECRET, f"{t}.".encode() + body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, header.get("v1", "")):
        abort(400)

    evento = request.get_json()
    encolar_para_procesar(evento)
    return "", 200

Reintentos y confiabilidad#

• Responde con cualquier código 2xx para confirmar la recepción. Cualquier otra cosa cuenta como fallo.
• Si tu endpoint falla o no responde, R2 reintenta con espera creciente: hasta 6 intentos a lo largo de varias horas.
• Un endpoint que falla muchas veces seguidas se desactiva solo; el dueño lo reactiva desde su panel cuando lo arregla.
• Responde rápido (menos de 5 segundos): confirma la recepción y procesa en segundo plano. Si tardas, R2 lo toma como timeout y reintenta.
• Puede haber entregas duplicadas en casos límite: usa R2-Delivery-Id para deduplicar y haz tu procesamiento idempotente.

Probar sin esperar un evento real#

Desde el panel del negocio (Configuración → R2 Connect API → Webhooks) hay un botón “Enviar evento de prueba” que dispara un aviso firmado con el mismo esquema que uno real — todos los campos de la tabla de arriba, con una reserva ficticia a 7 días de hoy. Si el endpoint está suscrito a varios eventos, se puede elegir cuál disparar, así pruebas la cancelación sin cancelar nada de verdad. El aviso trae "test": true, el order_number R2-TEST-0000 y una nota aclaratoria, para que tu sistema lo descarte sin tocar tus datos.

Registro de entregas#

Cada intento de envío queda registrado y el dueño del negocio lo consulta en su panel, en la misma sección de Webhooks: qué evento fue, si se entregó, cuántos intentos llevó, con qué código HTTP respondió tu servidor y cuándo. Es la forma de resolver un “no me llegó”: ahí se ve si R2 lo intentó y qué contestó tu endpoint.

• El registro conserva los últimos 30 días; las entregas ya terminadas se purgan después.
• No guarda el cuerpo del aviso, solo el resultado del intento. Si necesitas auditar el contenido, registra el payload de tu lado cuando lo recibas.
• La consulta vive en el panel del negocio: no hay un endpoint de la API para leer el registro. Si eres el integrador, pídele al hotel que te lo comparta cuando haga falta diagnosticar.