Webhooks

BoostAPI expone varios endpoints de webhook para recibir eventos de sistemas externos. Estos endpoints no requieren autenticacion JWT – usan sus propios mecanismos de validacion.

Webhook de Communications (Mensajeria)

POST /api/interactions/webhooks/communications

Este es el webhook principal para recibir eventos del servicio de Communications (WhatsApp, Instagram, Messenger).

Flujo de procesamiento

1. El servicio de Communications recibe un evento de Meta (WhatsApp, etc.)
2. Lo reenvia al webhook de BoostAPI
3. BoostAPI normaliza el payload a formato canonico
4. Valida la estructura del evento
5. Encola el evento para procesamiento
6. El InteractionsInlineWorkerService procesa la cola
7. El InteractionsProjectionService actualiza el estado local
8. Se emite un evento WebSocket a los clientes suscritos

Configuracion del webhook

La URL del webhook se construye automaticamente:

• Produccion: {BOOST_PUBLIC_BASE_URL}/api/interactions/webhooks/communications
• Preview: Se auto-detecta desde RENDER_EXTERNAL_URL
• Desarrollo: Via Cloudflare Quick Tunnel (si COMMUNICATIONS_DEV_TUNNEL_ENABLED=true)

Sincronizacion del webhook

El webhook se puede sincronizar de varias formas:

Variable	Descripcion	Default
COMMUNICATIONS_DEV_WEBHOOK_RESYNC_ENABLED	Re-sync en dev al arrancar	false
COMMUNICATIONS_BOOT_WEBHOOK_RESYNC_ENABLED	Re-sync al arrancar (preview/prod)	false
COMMUNICATIONS_USER_WEBHOOK_RESYNC_ENABLED	Re-sync en login/cambio de entidad	false

Tambien se puede sincronizar manualmente desde el Command Palette del modulo de Communications (requiere permiso communications.command_palette.view).

Webhook de formularios

POST /api/interactions/forms/ingest

Recibe eventos de envio de formularios web. Crea contactos automaticamente a partir de los datos del formulario y los asocia a la entidad correspondiente.

Uso tipico

Formularios de contacto en landing pages que envian datos directamente a BoostAPI para crear leads/contactos.

Webhook de pagos

POST /api/payments/webhooks

Endpoint placeholder para recibir eventos de plataformas de pago. Actualmente solo registra los eventos en logs.

GET /api/payments/webhooks/health

Health check para verificar que el endpoint esta disponible.

Administracion de Communications

Los operadores privilegiados pueden gestionar la configuracion del webhook desde endpoints protegidos:

Metodo	Ruta	Descripcion
POST	/interactions/communications/webhook-sync	Sincronizar webhook manualmente
POST	/interactions/communications/meta-token-rotate	Rotar token de Meta
POST	/interactions/communications/manual-login	Login manual en Communications

Estos endpoints requieren JWT + que el email del usuario este en COMMUNICATIONS_PRIVILEGED_OPERATOR_EMAILS.

Seguridad de webhooks

• Los webhooks de Communications se validan por estructura del payload (no por secret compartido – la validacion ocurre en el servicio de Communications).
• Los webhooks de formularios validan la estructura del evento.
• Los webhooks de pagos son placeholder y solo logean.
• Todos los webhooks estan excluidos de CORS (server-to-server).

Referencia privada: Ver BoostAPI/docs/interactions-outbound-channels-runbook.md para el runbook completo de canales de comunicacion y su configuracion.