The most up-to-date documentation for the Cloud Humans APIs is at docs.cloudhumans.com/api-reference. If this article and the reference disagree, the reference prevails.
When to use this
- You want to register a URL to receive Cloud Chat events
- You registered a webhook and nothing arrives at your endpoint
There are two different paths
Picking the wrong path is the most common reason a webhook never fires.
1. Integration webhook (the standard registration)
Configurações (Settings) > Integrações (Integrations) > Webhooks > Adicionar novo Webhook (Add new Webhook)
You provide:
- URL do Webhook (Webhook URL) — the endpoint that will receive the POST
- Eventos (Events) — which ones to subscribe to: conversation created, conversation updated, conversation status changed, message created, message updated, contact created, contact updated, chat widget opened by the user
You can register several webhooks in the same account, each with its own URL and its own list of events.
This registration requires the Administrator profile. If the Integrations menu does not appear, it is a permissions issue.
2. Automation that fires a webhook
Configurações (Settings) > Automação (Automation) > Adicionar regra de automação (Add automation rule)
Here you are not registering a webhook: you create a rule with conditions and choose the Enviar Evento Webhook (Send Webhook Event) action, pasting the URL into the action's field.
Which one should you use?
| You want to... | Use |
|---|---|
| Receive every event of a type (e.g., every message created) | Integrations > Webhooks |
| Receive them only in specific cases (e.g., only when the conversation has a tag) | Automation with the Send Webhook Event action |
You can tell the two apart at your endpoint by the payload's event field: the Integrations webhook sends the event name (e.g., message_created); automation sends it with a prefix (e.g., automation_event.message_created).
An Integrations webhook with "Mensagem criada" (Message created) fires on all messages in the account — including outgoing ones and those from every channel. If the volume is high, prefer automation with conditions.