Configuración de Webhooks

Acceso al Dashboard

Para configurar webhooks, debe acceder al dashboard de administración de Quralo Negocios con credenciales de administrador de su organización.

1. Inicie sesión en negocios.quralo.com
2. Navegue a Interoperabilidad > Webhooks

Crear un Nuevo Webhook

Paso 1: Información Básica

Complete los siguientes campos:

• Nombre del webhook: Identificador descriptivo para este webhook
• Descripción (opcional): Breve descripción del propósito
• URL: Endpoint HTTPS de su sistema HIS donde recibirá las notificaciones
• Ambiente: Seleccione entre Sandbox o Producción

Recomendación

Use nombres descriptivos como "HIS-Recetas-Produccion" o "Sistema-Principal-Consultas" para facilitar la gestión.

Paso 2: Credenciales de Seguridad

Al crear el webhook, el sistema generará automáticamente:

• Token de autenticación: Token Bearer para el header Authorization
• Secret: Clave secreta para generar y verificar la firma HMAC

Importante

• Estas credenciales solo se muestran una vez
• Guárdelas en un lugar seguro antes de cerrar la ventana
• Si las pierde, deberá regenerar el webhook

Paso 3: Configuración de Eventos

Seleccione qué tipos de eventos desea recibir:

• Consultas Médicas (encounter.created)
• Recetas Electrónicas (medication_request.created)
• Prescripción de Servicios (service_request.created): Solicitudes de estudios de laboratorio, imágenes, procedimientos, tratamientos y derivaciones.
• Prescripción de Dispositivos (device_request.created)

Ambientes Disponibles

Sandbox

• Propósito: Testing y desarrollo
• URL Base: https://sandbox-api.quralo.com
• Datos: Datos de prueba, no afecta producción
• Límites: Sin límites de rate limiting

Producción

• Propósito: Uso en vivo con datos reales
• URL Base: https://api.quralo.com
• Datos: Datos médicos reales de pacientes
• Límites: Rate limiting según su plan

Requisitos del Endpoint

Su endpoint debe cumplir con los siguientes requisitos:

Protocolo y Método

• Protocolo: HTTPS obligatorio
• Método: POST
• Content-Type: application/json

Tiempo de Respuesta

• Timeout: Máximo 30 segundos
• Recomendado: Responder en menos de 5 segundos

Códigos de Respuesta

• 2xx: Evento procesado correctamente
• 4xx: Error en el payload o autenticación
• 5xx: Error interno, se reintentará

Validación del Endpoint

Antes de activar el webhook, Quralo realiza una validación:

1. Test de Conectividad: Verifica que el endpoint responda
2. Test de Autenticación: Valida que acepte el token Bearer
3. Test de Firma: Confirma que verifique correctamente las firmas HMAC

POST /su-endpoint-webhook
Authorization: Bearer validation-token
X-Webhook-Event: webhook.validation
X-Webhook-Signature: sha256=test-signature
Content-Type: application/json

{
  "event": "webhook.validation",
  "timestamp": "2023-06-09T10:00:00Z",
  "data": {
    "test": true,
    "webhook_id": "webhook_12345"
  }
}

Respuesta esperada:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "message": "Webhook validation successful"
}

Gestión de Webhooks

Lista de Webhooks Configurados

El dashboard muestra todos los webhooks configurados con:

• Nombre y descripción
• URL del endpoint
• Ambiente (Sandbox/Producción)
• Estado (Activo/Inactivo/Error)
• Fecha de creación
• Último uso

Acciones Disponibles

• ✏️ Editar: Modificar nombre, descripción o URL
• 🔄 Regenerar: Crear nuevas credenciales de seguridad
• ⏸️ Pausar: Deshabilitar temporalmente
• 🗑️ Eliminar: Remover permanentemente

Logs y Monitoreo

Acceda a logs detallados de cada webhook:

• Historial de entregas: Timestamp, evento, respuesta HTTP
• Errores: Detalles de fallos y reintentos
• Métricas: Volumen, latencia, tasa de éxito

Límites y Restricciones

Por Organización

• Máximo de webhooks: 10 por ambiente
• Rate limiting: 1000 eventos/minuto en producción
• Retención de logs: 30 días

Por Webhook

• Payload máximo: 1MB
• Reintentos: Máximo 5 intentos
• TTL de eventos: 24 horas

Mejores Prácticas

Naming Convention

{Sistema}-{TipoEvento}-{Ambiente}
Ejemplos:
- HIS-Principal-Recetas-Prod
- Sistema-Laboratorio-Sandbox
- EMR-Consultas-Produccion

URLs Recomendadas

https://tu-dominio.com/webhooks/quralo
https://api.tu-his.com/integrations/quralo/webhook
https://his.hospital.com/api/v1/webhooks/quralo

Seguridad

• Use HTTPS exclusivamente
• Almacene credenciales en variables de entorno
• Implemente logging de seguridad
• Monitore intentos de acceso no autorizado

Siguiente Paso

Una vez configurado el webhook, continúe con la implementación de seguridad para entender cómo validar correctamente las solicitudes entrantes.