> ## 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
> Connect any system that can send and receive HTTP to ChatCLI: post a JSON message with a shared secret, and get the progress and the reply posted back to your callback URL.
The generic webhook is the channel for everything else: an internal chat, a ticketing system, a CI job or a script. Your system **posts a JSON message** to the gateway, and the gateway **posts the replies back** to a callback URL you choose. Both directions carry the same shared secret.
| | Webhook |
| - | - |
| Transport | An HTTP endpoint the gateway serves, plus a callback URL it posts to |
| Who can talk to the agent | Callers that send the shared secret |
| Voice in | Yes, as base64 or a URL in the request |
| Voice replies | No (text only) |
| Images in | Yes, as base64 or a URL in the request |
| Images out | Yes, as base64 in the callback |
| "Working on it" signal | One short notice posted to the callback if the reply takes more than about 2 seconds |
## Set it up
```bash theme={"system"}
export CHATCLI_WEBHOOK_ADDR=":8083"
export CHATCLI_WEBHOOK_SECRET="a-long-random-string"
export CHATCLI_WEBHOOK_CALLBACK_URL="https://your-app.example.com/chatcli/replies"
# export CHATCLI_WEBHOOK_PATH="/inbound" # the default
```
```text theme={"system"}
/gateway start
/gateway status # webhook should be listed
```
```bash theme={"system"}
curl -X POST http://localhost:8083/inbound \
-H "Content-Type: application/json" \
-H "X-ChatCLI-Secret: a-long-random-string" \
-d '{"chat_id": "ticket-42", "user_id": "alice", "text": "summarize the last deploy log"}'
```
The gateway answers `202 Accepted` at once; the progress and the reply arrive at your callback URL.
## Environment variables
| Variable | Required | Default | What it does |
| - | - | - | - |
| `CHATCLI_WEBHOOK_ADDR` | yes | — | Address the endpoint binds, for example `:8083`. The adapter starts when it is set. |
| `CHATCLI_WEBHOOK_SECRET` | yes, in practice | — | Shared secret checked on every request in `X-ChatCLI-Secret` and sent back on every callback. Without it **every request is refused** with `401`, and a warning is logged at start. |
| `CHATCLI_WEBHOOK_CALLBACK_URL` | yes, to get replies | — | Where the gateway posts the progress and the reply. Without it requests are still accepted and run, but **the replies are not delivered anywhere**; a warning is logged at start. |
| `CHATCLI_WEBHOOK_PATH` | no | `/inbound` | Path of the endpoint. |
| `CHATCLI_WEBHOOK_HOME_CHANNEL` | no | — | `chat_id` used for [proactive messages](/gateway/proactive-messaging) sent with `@send webhook`. |
## The request
`POST` to `CHATCLI_WEBHOOK_PATH` with `Content-Type: application/json` and the `X-ChatCLI-Secret` header:
| Field | Required | Meaning |
| - | - | - |
| `chat_id` | yes | The conversation. Messages with the same `chat_id` share context. |
| `user_id` | no | Who sent it; used to tell people apart in the [Conversation Hub](/gateway/conversation-hub). |
| `text` | one of text, audio or image | The message. |
| `audio_b64` or `audio_url` | no | A voice message, inline as base64 or as a URL the gateway downloads. It is transcribed before the agent runs. |
| `audio_mime` | no | The audio's MIME type, for example `audio/ogg`. |
| `image_b64` or `image_url` | no | An image, inline as base64 or as a URL the gateway downloads. |
| `image_mime` | no | The image's MIME type, for example `image/png`. |
| Response | When |
| - | - |
| `202 Accepted` | The message was queued. |
| `400 Bad Request` | The body is not valid JSON, `chat_id` is missing, base64 does not decode, or there is no text, audio or image. |
| `401 Unauthorized` | The secret is missing or wrong, or `CHATCLI_WEBHOOK_SECRET` is not set. |
| `405 Method Not Allowed` | Anything other than `POST`. |
| `503 Service Unavailable` | The gateway is shutting down. |
The request body is limited to the audio size cap plus 1 MB, about 21 MB with the default `CHATCLI_GATEWAY_MAX_AUDIO_BYTES`.
## The callbacks
For each message the gateway posts JSON to `CHATCLI_WEBHOOK_CALLBACK_URL`, with `Content-Type: application/json` and the same `X-ChatCLI-Secret` header so your endpoint can check where it came from:
```json theme={"system"}
{
"chat_id": "ticket-42",
"text": "The last deploy finished in 4m12s; two warnings, no errors."
}
```
When the reply carries an image, the body also has `image_b64`, and `image_mime` and `image_filename` when they are known.
A single message can produce several callbacks with this same shape: the "working on it" notice, progress updates while the agent works, and the final reply. There is no field telling them apart; the final reply is the last one. Any `2xx` answer from your endpoint counts as delivered.
## Security
* **Keep the secret long and random**, and serve the endpoint over HTTPS when it is reachable from other machines.
* `audio_url` and `image_url` are downloaded by the gateway itself, so whoever holds the secret can make the gateway fetch a URL from its own network.
* Each message runs the agent with its tools and shell, without confirmations. Harden it with [security mode](/security/overview).
## Limits
* A reply is cut at **3500 characters** and ends with `…`.
* Only text and images are posted back; voice replies are not sent on this channel.
## See also
How messages run, voice, images, continuity and the other channels.
Let the agent post to your callback on its own with `@send`.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.