Webhooks de CapData

CapData puede notificar a tu sistema en tiempo real sobre eventos importantes, como la creación de una nueva reserva, enviando una petición POST a una URL que tú especifiques. Esto te permite reaccionar instantáneamente a los datos extraídos.

1. Cómo Configurar tu URL de Webhook

Para recibir webhooks, debes configurar tu "Endpoint de Webhook" en el portal de CapData:

1. Inicia sesión en tu Portal CapData.
2. Navega a la sección Integraciones en el menú lateral.
3. Selecciona la opción Webhook General.
4. Introduce la URL de tu servidor que recibirá las peticiones POST (ej: https://miservidor.com/recibir-capdata-webhook).
5. Guarda los cambios. A partir de ese momento, CapData comenzará a enviar eventos a esa URL.

2. Estructura del Payload del Webhook

Cuando ocurre un evento, enviaremos una petición POST a tu URL con un cuerpo JSON. La estructura del payload siempre contiene información sobre el evento, el contexto de la cuenta y quién originó la acción.

Ejemplo: Evento new_flight_reservation_from_extension

Este evento se dispara cuando se extrae una nueva reserva a través de la API General (ej. extensión de Chrome).

{
    "event_type": "new_flight_reservation_from_extension",
    "reservation_data": [
        {
            "codigo_reserva": "XYZ123",
            "nombre_pasajero": "MARIA LOPEZ",
            "fecha_ida": "25/12/2025",
            "aerolinea": "Vueling"
            // ... otros datos de la reserva
        }
    ],
    "webhook_account_context": {
        "propietario_id": 1,
        "propietario_name": "Propietario Principal",
        "propietario_email": "propietario@email.com",
        "propietario_slug": "propietario-principal"
    },
    "action_originator": {
        "actor_type": "agent",
        "actor_id": 101,
        "actor_name": "Agente de Soporte",
        "actor_username": "agente.soporte",
        "actor_token_used": "el_token_del_agente_usado",
        "agent_belongs_to_client_id": 15,
        "agent_belongs_to_client_name": "Agencia de Viajes Demo",
        "agent_belongs_to_client_type": "agencia"
    }
}

Ejemplo: Evento flight_reservation_updated

Este evento se envía cuando se actualiza una reserva existente mediante /api/update_reservation. Incluye un sello temporal updated_at en formato ISO 8601.

{
  "event_type": "flight_reservation_updated",
  "reservation_data": {
    "codigo_reserva": "ABCDEF",
    "nombre_pasajero": "Juan Pérez García",
    "fecha_ida": "2025-10-15",
    "fecha_vuelta": "2025-10-22",
    "aerolinea": "Iberia",
    "precio": "250.50"
    // ... resto de campos según tu modelo de reserva
  },
  "updated_at": "2025-05-12T10:15:30Z",
  "webhook_account_context": {
    "propietario_id": 1,
    "propietario_name": "Propietario Principal",
    "propietario_email": "propietario@email.com",
    "propietario_slug": "propietario-principal"
  },
  "action_originator": {
    "actor_type": "owner",
    "actor_id": 1,
    "actor_name": "Propietario Principal"
    // o "agent"/"agency" si aplica
  }
}

Claves del Payload

• event_type: String que identifica el tipo de evento (ej: new_flight_reservation_from_extension, flight_reservation_updated).
• reservation_data: Un objeto o un array con los datos de las reservas relacionadas con el evento.
• updated_at: (solo en eventos de actualización) sello temporal ISO 8601.
• webhook_account_context: Identifica el Propietario al que pertenece el webhook y los datos.
• action_originator: Detalla quién realizó la acción (propietario, agencia o agente).

3. Buenas Prácticas y Seguridad

• Responde rápidamente: Tu endpoint debe responder con 200 OK lo antes posible para confirmar la recepción. Procesa de forma asíncrona si tu lógica es pesada.
• Verifica el origen: Actualmente, la plataforma no envía una firma HMAC por defecto. Para mayor seguridad, puedes proteger tu endpoint exigiendo un Bearer token propio (por ejemplo, en la cabecera Authorization) o un parámetro secreto en la URL. Si necesitas validación por firma, contacta con nosotros para habilitar cabeceras de firma HMAC.
• Maneja duplicados (idempotencia): Es posible recibir el mismo evento más de una vez (por red o reintentos). Utiliza event_type junto con identificadores de negocio (p. ej., codigo_reserva) y, si aplica, updated_at para deduplicar.

4. Cabeceras recomendadas (para tu endpoint)

Aunque CapData envía un Content-Type: application/json, te recomendamos que tu endpoint también:

• Exija autenticación propia (p. ej., Authorization: Bearer <tu_secreto>) o un token en la URL.
• Registre trazas de la petición (método, ruta, cabeceras mínimas, tamaño del cuerpo) para depuración.
• Implemente verificación de firma HMAC (opcional, si la habilitas con nosotros) utilizando una cabecera como X-CapData-Signature que firme el body con HMAC-SHA256 y un secreto compartido.

5. Idempotencia y Reintentos

Diseña tu manejador para que sea idempotente:

• Genera una “clave de evento” con event_type + codigo_reserva (u otro identificador de negocio) + updated_at cuando exista.
• Si ya procesaste esa clave, responde 200 OK y termina sin efectos secundarios.
• En caso de errores temporales en tu servidor, devuelve 5xx. Es recomendable que tu infraestructura permita reintentos controlados.