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

# Requests your agents send

> Receive signed chat and voice requests, store secret headers and handle the inbound call check.

Chat API Call steps, pre/post API actions, workflow tools and voice custom functions can call your services.

## Secret headers

Where a header editor is available, turn on the row's **Secret** switch. The value is encrypted and never shown again.

Saved values stay on the server. Request logs show secret values as \[secret] and signatures as \[signature].

Workflow tools have no header editor. Their configured headers are literal values. Workflow requests are still signed.

## Signing and reserved names

Agent requests use the organization's **Request signing** secret in **Settings → Integrations → Signing secrets**.

Verify them with the [shared recipe](https://hellotars.com/docs/developer/verify-requests.md). During rotation, requests include signatures for both current and retiring secrets.

These names are reserved, regardless of case:

* X-Tars-Signature
* X-Tars-Event-Id
* X-Tars-Request-Id
* X-Tars-Conversation-Id
* X-Tars-Call-Id
* X-Tars-Delivery-Id

Voice custom functions also reserve Content-Type. Chat requests can set their own Content-Type.

X-Tars-Request-Id identifies the logical request and stays the same on retries. Conversation and call headers appear when applicable.

## Inbound call check

Configure an HTTPS check URL on an inbound phone number. Tars calls it before choosing how to handle the incoming call.

The check sends POST once with a five-second timeout. Verify its signature using the organization's Request signing secret.

### Request body

| Field | Meaning |
| - | - |
| event | call\_inbound |
| id | req\_ followed by the call ID |
| timestamp | Request time in milliseconds |
| callInbound.callId | Call ID |
| callInbound.numberId | Receiving phone-number record ID |
| callInbound.numberE164 | Receiving number |
| callInbound.agentId | Bound agent ID, or null |
| callInbound.agentVersion | Bound published version, or null |
| callInbound.fromNumber | Calling number, or null |
| callInbound.toNumber | Dialed number |
| callInbound.sipHeaders | SIP header map |

### Accept

Return a 2xx application/json response containing an empty object to keep the number's normal binding.

```json theme={null}
{}
```

### Reject

Return reject.reason as a non-empty string. This ends the call with rejected\_by\_webhook.

```json theme={null}
{ "reject": { "reason": "Caller is not eligible" } }
```

### Override

Return an override object with optional agentId, variables, metadata, language and storageMode.

```json theme={null}
{
  "override": {
    "agentId": "VOICE_AGENT_ID",
    "variables": { "accountTier": "priority" },
    "metadata": { "source": "inbound-check" },
    "language": "en",
    "storageMode": "everything_except_pii"
  }
}
```

variables is a map of string values. storageMode is everything, everything\_except\_pii or basic\_attributes\_only.

The override agent must be active, published, in the same organization and eligible for inbound calls. An invalid override falls back to the normal binding.

### Failure behavior

Timeouts, connection errors, non-2xx responses, invalid JSON and missing signing configuration fall back to the number's normal binding.

Redirects are not followed. There is one attempt, so the check must respond promptly.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.