Webhooks en Adminia Manager: notificaciones en tiempo real para tu administración

Un webhook es básicamente Adminia Manager golpeándote la puerta cuando pasa algo importante: 'che, llegó un pago de la unidad 3°B', 'che, se generó un incidente urgente', 'che, la liquidación de mayo está publicada'. En lugar de tu sistema consultando cada 5 minutos si hay novedades (polling), es Adminia el que te avisa al instante.

Esto cambia tu operatoria de **reactiva a proactiva**: el administrador se entera antes de que el propietario llame.

Eventos que dispara Adminia Manager

Estos son los eventos más usados que podés suscribir desde **Configuración → Integraciones → Webhooks**:

• `collection.received` — entró un cobro (incluye monto, unidad, método).
• `collection.unidentified` — cobró pero no pudo identificarse, requiere acción.
• `liquidation.published` — se publicó la liquidación mensual con totales.
• `incident.created` — propietario reportó un incidente desde el portal.
• `incident.priority_high` — incidente clasificado por la IA como urgente.
• `assembly.scheduled` — se convocó una asamblea (ordinaria o extraordinaria).
• `assembly.minutes_signed` — se firmó digitalmente el acta de asamblea.
• `expense.created` — se cargó un gasto (manual o automático).
• `unit.debt_threshold` — una unidad superó X días de deuda.
• `user.invited` — se invitó a un nuevo propietario al portal.

Firma HMAC: por qué importa

Cada webhook que enviamos viene firmado con HMAC-SHA256 usando un secret que solo conocés vos. Esto garantiza autenticidad (el request realmente lo mandó Adminia, no un atacante) e integridad (el body no fue manipulado).

El header `X-Adminia-Signature` contiene el hash. Tu endpoint debe re-calcularlo con el secret y compararlo. Si no coincide, descartás el evento. Si tu webhook handler no valida la firma, **estás dejando una puerta abierta** para que cualquiera dispare cobros falsos en tu sistema.

Caso 1: Slack/Teams del equipo

Un canal `#cobros-hoy` en Slack donde cae cada cobro recibido. El equipo de cobranzas ve en vivo y no necesita abrir Adminia. Tiempo de armado: 10 minutos con n8n o Make.

Caso 2: alerta WhatsApp para incidentes urgentes

Cuando llega `incident.priority_high` (la IA clasificó algo como urgente, ej: 'pérdida de agua piso 8'), el webhook dispara un mensaje WhatsApp al celular del administrador y al encargado, con la dirección y la foto. Sin esperar a que el propietario llame.

Caso 3: sincronizar liquidaciones a Google Drive

Suscribís `liquidation.published`, y un automation copia el PDF a una carpeta compartida con el consejo y manda un mail a los miembros. Tres tareas manuales eliminadas por edificio por mes.

Caso 4: tablero de cobranza del directorio

Cada `collection.received` actualiza una fila en una Google Sheet o Airtable, y el directorio ve el gráfico de recaudación del día sin reportes manuales.

Caso 5: contabilidad automática

`expense.created` dispara una entrada en Xubio o Holded con la categoría correspondiente, el comprobante adjunto y el centro de costos asignado al edificio.

Caso 6: notificación al consejo de morosos

`unit.debt_threshold` (umbral configurable, típicamente 60 o 90 días) dispara un email al presidente del consejo con la lista de morosos antes de que el administrador tenga que armarla a mano.

Buenas prácticas

• Responder `200 OK` en menos de 5 segundos. Si tu lógica es lenta, encolá y procesá async.
• Idempotencia: el mismo evento puede llegar dos veces (retries). Guardá el `event_id` y descartá duplicados.
• Reintentos: Adminia reintenta con exponential backoff hasta 24 hs si recibe un error 5xx.
• Endpoint HTTPS obligatorio. No aceptamos webhooks a HTTP plano.
• Logueá todos los webhooks recibidos los primeros 30 días para debug.

Preguntas frecuentes