> ## Documentation Index
> Fetch the complete documentation index at: https://docs.callkaro.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook

Every chat agent can POST its own conversation events to a URL you control — separate from the account-level webhook in Settings. Both can be active at once, each with its own event list.

## Settings

| Setting         | Description                                                                |
| --------------- | -------------------------------------------------------------------------- |
| **Webhook URL** | Where events are POSTed, as `{ event, data }`. Leave empty to send nothing |
| **Events**      | Only the events you select are sent                                        |
| **Headers**     | Optional headers sent with every request                                   |

## Events

A chat agent's webhook covers conversations only. `call_ended` is not offered here — it comes from the call pipeline, which knows the voice agent that ran the call.

| Event                    | Fires when                                                     |
| ------------------------ | -------------------------------------------------------------- |
| `message_received`       | Someone sent your agent a message                              |
| `message_sent`           | Your agent sent a message — failed sends included, with status |
| `template_sent`          | A WhatsApp template went out                                   |
| `message_status_updated` | Delivery status changed: delivered, read or failed             |

<Warning>
  `message_status_updated` is **high volume** — every outbound message reports two or three times. Subscribe to it only if you are actually processing delivery state, and make sure your endpoint can absorb the rate.
</Warning>

<Note>
  Setting a URL with no events selected sends nothing. The builder warns you when that happens.
</Note>

## Headers

Each header row is a key plus a value from one of two sources:

| Source      | Use for                                                            |
| ----------- | ------------------------------------------------------------------ |
| **Secrets** | Anything sensitive — pick a secret from your Secrets Vault by name |
| **Custom**  | Non-sensitive constants, like a fixed `X-Source` tag               |

<Warning>
  Never paste a token, API key or signing secret in as a custom value. Save it in the [Secrets Vault](/agents/configurations/secrets) and reference it — vault values are stored encrypted, custom values are stored as typed.
</Warning>

## Related

<CardGroup cols={2}>
  <Card title="Webhook reference" icon="book" href="/webhook/introduction">
    Payload shapes and delivery semantics
  </Card>

  <Card title="Secrets" icon="key" href="/agents/configurations/secrets">
    Where credentials belong
  </Card>
</CardGroup>