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

# Webhooks: get call results in your own system

> Set a webhook on your agent to receive each call's transcript, outcome and recording when it ends, plus no answer and error events for outbound calls.

A webhook sends call results to a URL you own. When a call with your agent ends, Hamsa posts the transcript, the outcome and a link to the recording. When an outbound call can't connect, it posts a `no_answer` or `error` event instead. Use it to update your CRM, open a ticket or start a follow-up.

## Set up a webhook

The webhook belongs to the agent. Every call with that agent sends to it: inbound, outbound, batch, website and test calls.

> [tab] Single prompt agent
>
> **1. Open Call webhook**
>
> In the agent, open **Configuration** > **Call webhook**.
>
> **2. Enter the URL**
>
> Enter your endpoint in **Webhook URL**. It must start with `https://`.
>
> **3. Choose the authentication**
>
> In **Authentication**, pick **No auth**, or **Bearer** and enter `Bearer <token>` in the secret field.
>
> ![Call webhook in a single prompt agent's Configuration: a Webhook URL and Bearer authentication with a Bearer token](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/call-webhook-single-prompt-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=a3a9df1a0fb3458894cbaaec31cf3a8b)
>
> **4. Publish**
>
> When you publish, Hamsa checks that the URL answers. If it doesn't within 2 seconds, publishing stops with "Webhook URL is not reachable".

> [tab] Flow agent
>
> **1. Open Call webhook**
>
> In the flow builder, open **Global settings** from the canvas toolbar, then **Call webhook**.
>
> **2. Enter the URL**
>
> Enter your endpoint in **Webhook URL**. Use an `https://` URL.
>
> **3. Choose the authentication**
>
> In **Authentication**, pick **No auth**, or **Bearer** and enter your token on its own, without the word `Bearer`.
>
> ![Call webhook in the flow builder's Global settings: a Webhook URL and Bearer authentication with the token on its own](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/call-webhook-flow-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=dd99570022a6921cedc4080926460933)
>
> **4. Save and publish**
>
> Save the flow and publish it so calls use the webhook.

Either way, Hamsa sends `Authorization: Bearer <token>` with each request. Check it on your side to make sure the request comes from Hamsa.

## Events

| Event | When it's sent |
| - | - |
| `call_end` | When a call ends, for every call that connected: phone, website, SDK, chat and tests. |
| `no_answer` | An outbound call wasn't answered: no answer, busy, declined or cancelled before pickup. |
| `error` | An outbound call couldn't be placed for another reason, for example a SIP error from your provider. |

Nothing is sent when a call starts or while it's in progress.

## Payload

Every event is a `POST` with a JSON body in the same envelope:

| Field | What it holds |
| - | - |
| `event_type` | `call_end`, `no_answer` or `error`. |
| `timestamp` | When Hamsa sent the event, in UTC ISO 8601. |
| `agent_name` | The agent's name. |
| `caller_info` | Who was on the call. Empty (`{}`) for `no_answer` and `error`. |
| `data` | The event's details (see below). |

### caller\_info

| Field | What it holds |
| - | - |
| `call_id` | The call's SIP call ID on phone calls, otherwise the call's ID. |
| `call_type` | `Phone`, `Web` or `Chat`. |
| `direction` | `Inbound` or `Outbound`. Website and SDK calls also say `Outbound`. |
| `call_start_time` | When the call started, in Unix seconds. |
| `user_number` | The caller's or recipient's phone number. |
| `agent_number` | Your Hamsa number on the call. |
| `agent_name` | The agent's name. On chat, the agent's ID. |
| `agent_id` | The agent's ID. |
| `sip_headers` | Inbound phone calls only: the SIP headers your provider sent. |

### call\_end

```json theme={null}
{
  "event_type": "call_end",
  "timestamp": "2026-10-31T09:15:02.481213Z",
  "agent_name": "Renewals agent",
  "caller_info": {
    "call_id": "SCL_k3j2h1g0f9",
    "call_type": "Phone",
    "direction": "Outbound",
    "call_start_time": 1761901801.52,
    "user_number": "+971501234567",
    "agent_number": "+14155550100",
    "agent_name": "Renewals agent",
    "agent_id": "8c1d2f3a-5b6e-4c7d-9e8f-0a1b2c3d4e5f"
  },
  "data": {
    "conversationId": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a9f8e7d6c",
    "callStartedAt": 1761901801520,
    "callEndedAt": 1761901898904,
    "recordingStartedAt": 1761901802113,
    "outcomeResult": {
      "renewal_confirmed": true,
      "default_params": { "customer_name": "Sara", "renewal_date": "15 November" }
    },
    "transcription": [
      { "Agent": "Hello Sara, I'm calling about your renewal.", "timestamp": 1761901802400, "recordingOffsetMs": 287 },
      { "User": "Yes, go ahead.", "timestamp": 1761901806950, "recordingOffsetMs": 4837 }
    ],
    "conversationRecording": "https://..."
  }
}
```

| Field in `data` | What it holds |
| - | - |
| `conversationId` | The call's ID. It matches the `jobId` the [outbound call API](https://docs.tryhamsa.com/agents/connect/outbound-calls.md) returns and the call in the [Conversation log](https://docs.tryhamsa.com/agents/monitor/conversation-log.md). |
| `callStartedAt`, `callEndedAt` | Start and end, in Unix milliseconds. |
| `recordingStartedAt` | When the recording began, in Unix milliseconds, or `null`. |
| `outcomeResult` | The fields of the agent's **Outcome**, if you set one up. Also `default_params` (the values the call started with) and, if a guardrail fired, `trippedGuardrails`. |
| `transcription` | The turns in order. Each has `Agent` or `User` with the text, and `timestamp`. Turns can also carry `recordingOffsetMs` (where the turn starts in the recording), `node_id` (the step, on flow agents), `metadata` and, on agent turns, `latency`. |
| `conversationRecording` | A signed link to the recording, or `null`. |

### no\_answer and error

```json theme={null}
{
  "event_type": "no_answer",
  "timestamp": "2026-10-31T09:20:44.019532Z",
  "agent_name": "Renewals agent",
  "caller_info": {},
  "data": {
    "conversationId": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
    "status": "NO_ANSWER",
    "errorMessage": "...",
    "errorStatusCode": "486",
    "default_params": { "customer_name": "Omar" }
  }
}
```

| Field in `data` | What it holds |
| - | - |
| `conversationId` | The call's ID. |
| `status` | `NO_ANSWER` or `FAILED`. |
| `errorMessage` | The dialing error. |
| `errorStatusCode` | The SIP status code. `408`, `480`, `486`, `487`, `600` and `603` mean no answer; anything else is an error. |
| `default_params` | The values the call started with, so you can match the event to your own record. |

## Delivery

* One `POST` per event, with `Content-Type: application/json`. Hamsa waits up to 30 seconds for your server.
* There are no retries. If your endpoint is down or times out, that event is lost.
* Any response counts as delivered, including `4xx` and `5xx`.
* Requests aren't signed. Use the Bearer token to check that a request is from Hamsa.
* Hamsa checks your TLS certificate, so a self-signed certificate fails. It follows redirects.
* `call_end` is sent after Hamsa has saved the call. If saving the call fails, no `call_end` is sent.

Answer quickly with a `200` and do slow work after you reply. If you need every call, compare against the [Conversation log](https://docs.tryhamsa.com/agents/monitor/conversation-log.md) now and then.

## Set the webhook through the API

If you create or update agents through the API, the webhook is two fields on the agent:

```json theme={null}
{
  "webhookUrl": "https://example.com/hamsa/webhook",
  "webhookAuth": { "authKey": "bearer", "authSecret": "YOUR_TOKEN" }
}
```

* Send the token in `authSecret`, with or without `Bearer `. Hamsa adds `Bearer ` only when the value doesn't already start with a scheme, so both arrive as `Bearer YOUR_TOKEN`.
* For no authentication, send `"webhookAuth": null` or leave it out.
* The API accepts any valid URL. Use `https://`.

## Related

> [card] [Make an outbound call](https://docs.tryhamsa.com/agents/connect/outbound-calls.md)
>
> Start a call and match its jobId in the webhook.

> [card] [Batch calls](https://docs.tryhamsa.com/agents/connect/batch-calls.md)
>
> Each call in a batch sends its own events.

> [card] [Call details](https://docs.tryhamsa.com/agents/monitor/call-details.md)
>
> The same transcript and outcome in the app.

> [card] [Conversation log](https://docs.tryhamsa.com/agents/monitor/conversation-log.md)
>
> Every call, to check against what you received.


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