Webhooks: Eventos y contratos

Catálogo de eventos webhook que MarIA emite hacia tu backend y llamadas al EHR/HIS

Los webhooks permiten que tu backend reciba notificaciones en tiempo real de lo que ocurre durante las llamadas y la gestión de citas. Se firman con HMAC-SHA256 para verificar su procedencia.

​

MarIA → Cliente (eventos)

Evento	Cuándo se emite	Acción típica
appointment.created	Tras crear una cita desde MarIA	Registrar en HIS, enviar confirmación al paciente
appointment.rescheduled	Tras reprogramar una cita	Actualizar en HIS, notificar al paciente
appointment.cancelled	Tras cancelar una cita	Actualizar en HIS, liberar el hueco
voice.call.status.updated	En cada cambio de estado de la llamada	Actualizar panel operativo / KPIs
voice.call.escalated	Cuando la llamada se transfiere a humano	Alertar al equipo de atención
voice.answer.updated	Cuando se captura una respuesta en llamada	Sincronizar con EHR o data warehouse
voice.transcript.created	Al finalizar la llamada	Indexar transcripción, QA de calidad

​

Integración EHR/HIS (MarIA llama a tu HIS)

MarIA invoca estos webhooks hacia tu sistema hospitalario durante la gestión de citas:

Webhook	Operación
appointment.getBenefits	Obtener coberturas/prestaciones disponibles
appointment.getSlots	Consultar huecos disponibles
appointment.create	Crear una cita
appointment.cancel	Cancelar una cita
appointment.reschedulePending	Marcar cita pendiente de reprogramación
appointment.getList	Listar las citas de un paciente
directory.centers	Listar centros disponibles
directory.professionals	Listar profesionales de un centro/servicio
patient.authenticate	Verificar identidad del paciente
patient.onboard	Registrar un nuevo paciente

​

Registro de webhooks

Registra los endpoints donde quieres recibir los eventos de MarIA:

curl -X POST "$BASE_URL/webhooks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "appointment.created",
    "url": "https://tu-backend.com/webhooks/maria",
    "auth": { "type": "hmac", "secret": "tu-secreto-hmac" }
  }'

​

Verificación de firma

Todos los eventos llevan la cabecera X-Integration-Signature: sha256=<hex> calculada sobre el cuerpo RAW. Consulta Verificación de firmas HMAC para ejemplos de código en Node.js y Python.

Consulta la sección Referencia de API para ver los payloads completos de cada evento en la especificación OpenAPI.