---
id: MGN-018-webhooks
title: Modulo Webhooks para Clinica Dental
type: Module
status: Draft
version: 1.0.0
created_date: 2026-01-13
updated_date: 2026-01-13
phase: 04-fase-saas
normativas: [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

```json
{
  "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

```json
{
  "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/](./requerimientos/)
- **Especificaciones:** [especificaciones/](./especificaciones/)
- **User Stories:** [historias-usuario/](./historias-usuario/)
- **Trazabilidad:** [implementacion/TRACEABILITY.yml](./implementacion/TRACEABILITY.yml)

---

## Referencias

- **Fuente:** [erp-core/MGN-018-webhooks](../../../../../erp-core/docs/04-fase-saas/MGN-018-webhooks/)
- **Arquitectura SaaS:** [ARQUITECTURA-SAAS.md](../../00-vision-general/ARQUITECTURA-SAAS.md)

---

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