> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhook
> Conecte ao ChatCLI qualquer sistema que envie e receba HTTP: poste uma mensagem JSON com um segredo compartilhado e receba o progresso e a resposta na sua URL de callback.
O webhook genérico é o canal para todo o resto: um chat interno, um sistema de tickets, um job de CI ou um script. O seu sistema **posta uma mensagem JSON** no gateway, e o gateway **posta as respostas de volta** numa URL de callback que você escolhe. Os dois sentidos levam o mesmo segredo compartilhado.
| | Webhook |
| - | - |
| Transporte | Um endpoint HTTP que o gateway serve, mais uma URL de callback para onde ele posta |
| Quem pode falar com o agente | Quem envia o segredo compartilhado |
| Voz recebida | Sim, como base64 ou URL na requisição |
| Respostas em voz | Não (só texto) |
| Imagens recebidas | Sim, como base64 ou URL na requisição |
| Imagens enviadas | Sim, como base64 no callback |
| Sinal de "trabalhando" | Um aviso curto postado no callback se a resposta passar de uns 2 segundos |
## Configuração
```bash theme={"system"}
export CHATCLI_WEBHOOK_ADDR=":8083"
export CHATCLI_WEBHOOK_SECRET="um-texto-longo-e-aleatorio"
export CHATCLI_WEBHOOK_CALLBACK_URL="https://seu-app.example.com/chatcli/respostas"
# export CHATCLI_WEBHOOK_PATH="/inbound" # o padrão
```
```text theme={"system"}
/gateway start
/gateway status # webhook deve aparecer
```
```bash theme={"system"}
curl -X POST http://localhost:8083/inbound \
-H "Content-Type: application/json" \
-H "X-ChatCLI-Secret: um-texto-longo-e-aleatorio" \
-d '{"chat_id": "ticket-42", "user_id": "alice", "text": "resuma o log do último deploy"}'
```
O gateway responde `202 Accepted` na hora; o progresso e a resposta chegam na sua URL de callback.
## Variáveis de ambiente
| Variável | Obrigatória | Padrão | O que faz |
| - | - | - | - |
| `CHATCLI_WEBHOOK_ADDR` | sim | — | Endereço do endpoint, por exemplo `:8083`. O adaptador liga quando ela está definida. |
| `CHATCLI_WEBHOOK_SECRET` | sim, na prática | — | Segredo compartilhado conferido em toda requisição no `X-ChatCLI-Secret` e reenviado em todo callback. Sem ele **toda requisição é recusada** com `401`, e um aviso é registrado no start. |
| `CHATCLI_WEBHOOK_CALLBACK_URL` | sim, para receber respostas | — | Para onde o gateway posta o progresso e a resposta. Sem ela as requisições continuam aceitas e rodam, mas **as respostas não são entregues a lugar nenhum**; um aviso é registrado no start. |
| `CHATCLI_WEBHOOK_PATH` | não | `/inbound` | Caminho do endpoint. |
| `CHATCLI_WEBHOOK_HOME_CHANNEL` | não | — | `chat_id` usado nas [mensagens proativas](/pt/gateway/proactive-messaging) enviadas com `@send webhook`. |
## A requisição
`POST` em `CHATCLI_WEBHOOK_PATH` com `Content-Type: application/json` e o header `X-ChatCLI-Secret`:
| Campo | Obrigatório | Significado |
| - | - | - |
| `chat_id` | sim | A conversa. Mensagens com o mesmo `chat_id` compartilham contexto. |
| `user_id` | não | Quem mandou; usado para diferenciar pessoas no [Conversation Hub](/pt/gateway/conversation-hub). |
| `text` | um entre texto, áudio ou imagem | A mensagem. |
| `audio_b64` ou `audio_url` | não | Uma mensagem de voz, em base64 ou como URL que o gateway baixa. É transcrita antes de o agente rodar. |
| `audio_mime` | não | O tipo MIME do áudio, por exemplo `audio/ogg`. |
| `image_b64` ou `image_url` | não | Uma imagem, em base64 ou como URL que o gateway baixa. |
| `image_mime` | não | O tipo MIME da imagem, por exemplo `image/png`. |
| Resposta | Quando |
| - | - |
| `202 Accepted` | A mensagem entrou na fila. |
| `400 Bad Request` | O corpo não é JSON válido, falta `chat_id`, o base64 não decodifica, ou não há texto, áudio nem imagem. |
| `401 Unauthorized` | O segredo está ausente ou errado, ou `CHATCLI_WEBHOOK_SECRET` não está definido. |
| `405 Method Not Allowed` | Qualquer coisa que não seja `POST`. |
| `503 Service Unavailable` | O gateway está desligando. |
O corpo da requisição é limitado ao teto de áudio mais 1 MB, uns 21 MB com o `CHATCLI_GATEWAY_MAX_AUDIO_BYTES` padrão.
## Os callbacks
Para cada mensagem o gateway posta JSON em `CHATCLI_WEBHOOK_CALLBACK_URL`, com `Content-Type: application/json` e o mesmo header `X-ChatCLI-Secret`, para que o seu endpoint confira a origem:
```json theme={"system"}
{
"chat_id": "ticket-42",
"text": "O último deploy terminou em 4m12s; dois avisos, nenhum erro."
}
```
Quando a resposta traz uma imagem, o corpo também tem `image_b64`, e `image_mime` e `image_filename` quando são conhecidos.
Uma mesma mensagem pode gerar vários callbacks com esse formato: o aviso de "trabalhando", atualizações de progresso enquanto o agente trabalha e a resposta final. Nenhum campo os diferencia; a resposta final é a última. Qualquer resposta `2xx` do seu endpoint conta como entregue.
## Segurança
* **Use um segredo longo e aleatório**, e sirva o endpoint por HTTPS quando ele for acessível de outras máquinas.
* `audio_url` e `image_url` são baixados pelo próprio gateway, então quem tem o segredo consegue fazer o gateway buscar uma URL da rede dele.
* Cada mensagem roda o agente com suas tools e o shell, sem confirmações. Endureça com o [modo de segurança](/pt/security/overview).
## Limites
* Uma resposta é cortada em **3500 caracteres** e termina com `…`.
* Só texto e imagens voltam no callback; respostas em voz não são enviadas neste canal.
## Veja também
Como as mensagens rodam, voz, imagens, continuidade e os outros canais.
Deixe o agente postar no seu callback por conta própria com `@send`.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.