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

# Webhooks

> Learn how to subscribe to Fluents.ai events and receive real-time JSON payloads at your own HTTP endpoints.

**Webhooks** let Fluents.ai send **real-time HTTP requests** to your systems when certain events happen during or after a call.

You can subscribe a single webhook to one or more event types (subscriptions), and each event will send a **JSON payload** to your URL.

Use webhooks when you want to:

* Store transcripts or post-call results
* Log call events in your own systems
* Trigger downstream workflows (analytics, alerts, CRM updates, etc.)

On this page:

* [Where to configure webhooks](#where-to-configure-webhooks)
* [Create a webhook](#create-a-webhook)
* [Available subscriptions](#available-subscriptions)
* [Webhook request format](#webhook-request-format)
* [Security recommendations](#security-recommendations)
* [How webhooks differ from Custom External Actions](#how-webhooks-differ-from-custom-external-actions)
* [Where to go next](#where-to-go-next)

***

## Where to configure webhooks

1. In the left-hand sidebar, click **Webhooks**.
2. You’ll see a list of existing webhooks for the current environment.
3. Each row typically shows:
   * **Label** – Name of the webhook.
   * **URL** – The target endpoint.
   * **Method** – Currently POST.
   * Other metadata such as ID or connection details.

From here you can:

* Click **Create Webhook** to add a new subscription.
* Use the three-dot menu next to an existing webhook to **edit** or **delete** it (depending on your UI).

***

## Create a webhook

To create a new webhook:

1. Go to **Webhooks** and click **Create Webhook**.

2. In the **New Webhook** dialog, fill in:

   * **Label**\
     A human‑friendly name for this webhook.\
     Example: `Store transcripts in data warehouse`.

   * **URL**\
     The endpoint on your server that will receive webhook events.\
     Example: `https://api.yourcompany.com/fluents/webhook`.

   * **Subscriptions**\
     Select one or more event types you want this webhook to receive\
     (see [Available subscriptions](#available-subscriptions) below).

   * **Method**\
     Currently **POST** is used for all webhooks.

   * **Account Connection** (optional)\
     In some setups you can associate the webhook with a specific account connection.\
     If you don’t use this yet, you can leave it at its default value.

3. Click **Create Webhook** to save.

From now on, whenever any of the selected events occur, Fluents.ai will send a POST request to your URL with a JSON payload.

***

## Available subscriptions

You can subscribe a webhook to one or more of the following event types:

* **Message**\
  Events related to messages exchanged during the call.

* **Action**\
  Events related to actions your agent performs (for example, certain phone actions or external actions).

* **Transcript**\
  Transcript-related events. Payloads typically include transcript text in the `payload` section.

* **Error**\
  Events when an error occurs during a call or processing pipeline.

* **Recording**\
  Events related to call recordings (for example, when a recording is available).

* **Human Detection**\
  Events indicating when a human is detected in the call flow, depending on your configuration.

* **Phone Call Did Not Connect**\
  Events when an attempted call failed to connect (for example, unreachable or busy).

* **Phone Call Connected**\
  Events when a call successfully connects.

* **Phone Call Ended**\
  Events when a call is finished.

* **Post-Call Processing Completed**\
  Events when **post-call processing is complete** and the **post-call result** (analysis / summary) is ready.\
  The payload includes the post‑call result content in the `payload` section so you can store or process it.

You can tick multiple subscriptions for the same webhook if you want a single endpoint to handle several event types.

***

## Webhook request format

All webhooks use:

* **HTTP method:** POST
* **Body:** JSON
* **Authentication:** No built-in signing yet (see [Security recommendations](#security-recommendations)).

The exact `payload` structure will vary by event type, but the top-level structure is generally consistent and includes:

* `call_id` – Unique ID of the call linked to this event.
* `type` – The event type (for example, `event_transcript`, `event_post_call_processing_completed`).
* `from_number` – The caller’s number.
* `to_number` – The number that was called.
* `is_outgoing` – `true` for outbound calls, `false` for inbound calls.
* `payload` – Event-specific data (transcript, post-call result, error details, etc.).

For example, a transcript-related event might look like this (dummy values):

```JSON theme={null}
{
  "call_id": "00000000-0000-0000-0000-000000000000",
  "type": "event_transcript",
  "from_number": "+15551112222",
  "to_number": "+15553334444",
  "is_outgoing": true,
  "payload": {
    "transcript": "Sample transcript text for this call..."
  }
}
```

For a **Post-Call Processing Completed** event, the `payload` would contain the post-call result or analysis text, for example:

* `payload.post_call_results` or a similar field, depending on your configuration.

Your endpoint should:

* Accept JSON POST requests.
* Parse the body.
* React based on `type` and the data inside `payload`.

***

## Security recommendations

Currently, Fluents.ai webhooks **do not** include a built-in signing mechanism (HMAC or shared secret).

To keep your webhook endpoints secure:

* Use a **secret, unguessable URL** for your webhook endpoint.
  * Example: `https://api.yourcompany.com/fluents/webhook/long-random-token`.
* Validate the data you receive and ignore unexpected payloads.
* Optionally limit access by:
  * Allowlisting IP ranges (if feasible in your infrastructure).
  * Adding your own authentication layer in front of the endpoint (for example, an API gateway).

Do not expose webhook endpoints that accept unauthenticated modifications to sensitive systems without additional checks.

***

## How webhooks differ from Custom External Actions

Webhooks and **Custom External Actions** both involve calling external URLs, but they serve different purposes:

* **Webhooks**

  * Triggered by **events** (for example, call connected, transcript chunk, post-call processing completed).
  * Are usually **one-way notifications** from Fluents.ai to your systems.
  * Do **not** pause the conversation or require an immediate response to continue the call.
  * Great for logging, analytics, syncing data to CRMs or data warehouses, and triggering asynchronous workflows.

* **Custom External Actions**
  * Are triggered **during** a conversation by the agent (function-based).
  * The agent **waits** for your API’s response and then uses that data to continue talking.
  * Ideal when the conversation must react in real time to your API (for example, look up an account and then read back the balance).

Use **webhooks** for event-driven integrations and background processing.\
Use **Custom External Actions** when the agent must call your API in the middle of a live call.

See the **[Actions – Custom External Actions](./actions)** guide for more about custom actions.

***

## Where to go next

* Learn how to create Custom External Actions that call your own APIs in the\
  **[Actions Feature Guide](./actions)**.

* Review how calls are logged and how post-call processing works in\
  **[Call history (Core Concept)](../concepts/call-history)** and\
  **[Agents – Post-Call Actions](../concepts/agent/post-call)**.

* Manage API keys and environments for your backend integrations in\
  **[Get API key](./account/get-api-key)** and **[Settings](./account/settings)**.