La documentación más actualizada de las APIs de Cloud Humans está en docs.cloudhumans.com/api-reference. En caso de discrepancia entre este artículo y la referencia, prevalece lo que está allí.
Cuándo usarlo
- Quieres registrar una URL para recibir eventos de Cloud Chat
- Registraste un webhook y no llega nada a tu endpoint
Son dos caminos diferentes
Elegir el camino equivocado es la causa más común de que un webhook no se dispare.
1. Webhook de integración (el registro estándar)
Configurações (Configuraciones) > Integrações (Integraciones) > Webhooks > Adicionar novo Webhook (Agregar nuevo Webhook)
Debes indicar:
- URL do Webhook (URL del Webhook) — el endpoint que recibirá el POST
- Eventos — cuáles suscribir: conversación creada, conversación actualizada, estado de conversación modificado, mensaje creado, mensaje actualizado, contacto creado, contacto actualizado, widget de chat abierto por el usuario
Puedes registrar varios webhooks en la misma cuenta, cada uno con su URL y su lista de eventos.
Este registro requiere el perfil Administrador. Si el menú Integraciones no aparece, es un tema de permisos.
2. Automatización que dispara un webhook
Configurações (Configuraciones) > Automação (Automatización) > Adicionar regra de automação (Agregar regla de automatización)
Aquí no registras un webhook: creas una regla con condiciones y eliges la acción Enviar Evento Webhook (Enviar Evento Webhook), pegando la URL en el campo de la acción.
¿Cuál usar?
| Quieres... | Usa |
|---|---|
| Recibir todos los eventos de un tipo (ej.: cada mensaje creado) | Integraciones > Webhooks |
| Recibirlos solo en casos específicos (ej.: solo cuando la conversación tiene una etiqueta) | Automatización con la acción Enviar Evento Webhook |
Puedes distinguir ambos en tu endpoint por el campo event del payload: el webhook de Integraciones envía el nombre del evento (ej.: message_created); la automatización lo envía con prefijo (ej.: automation_event.message_created).
Un webhook de Integraciones con "Mensagem criada" (Mensaje creado) se dispara en todos los mensajes de la cuenta — incluidos los salientes y los de todos los canales. Si el volumen es alto, prefiere la automatización con condiciones.