clinica-dental/docs/04-fase-saas/MGN-018-webhooks

id	title	type	status	version	created_date	updated_date	phase	normativas
MGN-018-webhooks	Modulo Webhooks para Clinica Dental	Module	Draft	1.0.0	2026-01-13	2026-01-13	04-fase-saas	NOM-013-SSA2-2015 LFPDPPP

MGN-018: Webhooks Outbound para Clinica Dental

Modulo: MGN-018 Nombre: Webhooks Outbound Fase: 04 - SaaS Estado: Pendiente Documentacion Ultima actualizacion: 2026-01-13

---

Descripcion

Sistema de webhooks outbound para notificar eventos de la clinica dental a sistemas externos. Permite a las clinicas registrar endpoints HTTP para recibir notificaciones automaticas cuando ocurren eventos como agendamiento de citas, finalizacion de tratamientos, actualizacion de odontogramas, pagos de servicios, etc.

---

Funcionalidades Principales

1. Registro de Endpoints - CRUD de endpoints webhook por clinica
2. Firma HMAC-SHA256 - Firma criptografica de payloads
3. Reintentos con Backoff - Politica de reintentos exponencial
4. Dead Letter Queue - Almacenamiento de entregas fallidas
5. Delivery Logs - Historial completo de entregas

---

Eventos Disponibles para Clinica Dental

Categoria	Eventos
Citas	cita.creada, cita.confirmada, cita.cancelada, cita.completada
Pacientes	paciente.creado, paciente.actualizado
Tratamientos	tratamiento.iniciado, tratamiento.completado, tratamiento.cancelado
Odontograma	odontograma.actualizado, pieza.tratada
Pagos	pago.recibido, pago.fallido
Presupuestos	presupuesto.creado, presupuesto.aprobado, presupuesto.rechazado

---

Casos de Uso Odontologicos

• Sincronizar pacientes con sistema de laboratorio dental
• Notificar a aseguradoras sobre tratamientos completados
• Actualizar sistema contable con pagos recibidos
• Integrar con Slack/Teams para alertas del equipo
• Trigger de recordatorios automaticos en herramientas externas
• Notificar a sistema de rayos X sobre nuevas citas

---

Arquitectura

+-------------------+     +-------------------+     +-------------------+
| Evento Dental     |---->| Webhook Service   |---->| BullMQ Queue      |
| (cita, tratam.)   |     | (enqueue)         |     | (webhooks)        |
+-------------------+     +-------------------+     +-------------------+
                                                           |
                                                           v
                                                 +-------------------+
                                                 | Webhook Processor |
                                                 | (worker)          |
                                                 +-------------------+
                                                           |
                                       +-------------------+-------------------+
                                       |                                       |
                                       v                                       v
                               +---------------+                       +---------------+
                               | HTTP POST     |                       | Retry Queue   |
                               | (lab dental,  |                       | (backoff)     |
                               |  aseguradora) |                       +---------------+
                               +---------------+                               |
                                       |                                       v (5 fails)
                                       v                               +---------------+
                               +---------------+                       | DLQ           |
                               | Delivery Log  |                       | (failed)      |
                               | (success)     |                       +---------------+
                               +---------------+

---

Ejemplo de Payload

Evento: cita.confirmada

{
  "event": "cita.confirmada",
  "timestamp": "2026-01-13T10:30:00Z",
  "webhook_id": "wh_dental_001",
  "data": {
    "cita_id": "cita_xyz789",
    "paciente": {
      "id": "pac_abc123",
      "nombre": "Maria Garcia",
      "telefono": "+521234567890"
    },
    "fecha": "2026-01-15",
    "hora": "10:00",
    "tratamiento": "Limpieza dental",
    "doctor": "Dr. Rodriguez",
    "sillon": 2,
    "duracion_minutos": 45
  }
}

Evento: tratamiento.completado

{
  "event": "tratamiento.completado",
  "timestamp": "2026-01-13T11:45:00Z",
  "webhook_id": "wh_dental_002",
  "data": {
    "tratamiento_id": "trat_def456",
    "paciente_id": "pac_abc123",
    "tipo": "Resina",
    "piezas_tratadas": ["16", "17"],
    "doctor": "Dr. Martinez",
    "costo": 1500.00,
    "moneda": "MXN",
    "notas": "Resina compuesta en molares superiores"
  }
}

---

Dependencias

Este modulo depende de:

• MGN-001 Auth (autenticacion de administradores)
• MGN-004 Tenants (aislamiento por clinica)
• MGN-017 Plans (feature gating - solo planes Clinica y Centro)

Modulos que dependen de este:

• Integraciones con laboratorios dentales
• Sistemas de aseguradoras
• Herramientas de notificacion

---

Seguridad y Normativas

Medida	Implementacion
HMAC signature	SHA-256 con secret por endpoint
Timestamp	Previene ataques de replay (5 min)
URL validation	Solo HTTPS en produccion
Timeout	30 segundos maximo
NOM-013-SSA2-2015	No enviar datos sensibles de salud sin consentimiento
LFPDPPP	Cumplimiento de privacidad de datos

Datos Sensibles

Los webhooks NO deben incluir:

• Expediente clinico completo
• Diagnosticos detallados
• Radiografias o imagenes
• Datos de pago completos

Para datos sensibles, el receptor debe hacer una consulta autenticada a la API.

---

Documentacion

• Requerimientos: requerimientos/
• Especificaciones: especificaciones/
• User Stories: historias-usuario/
• Trazabilidad: implementacion/TRACEABILITY.yml

---

Referencias

• Fuente: erp-core/MGN-018-webhooks
• Arquitectura SaaS: ARQUITECTURA-SAAS.md

---

Modulo: MGN-018-webhooks | Clinica Dental Propagado desde erp-core via erp-clinicas Actualizado: 2026-01-13