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

# Overview

> An overview of webhooks that Apten provides.

## Why use webhooks

The Apten API is designed to be used in real-time applications. Webhooks are a way to receive
real-time notifications from the Apten API when certain events occur. For example, you may want
to know when Apten tags a new lead, when a message is received from a lead, or when a lead opts out. Webhooks are a way for
the Apten API to send these real-time events to your application.

## Configuring webhooks

To configure webhooks, you must provide a URL where the Apten API can send events.
You can configure webhooks in the [Developer Portal](https://platform.attent.app/developer). Once
you have configured a webhook, the Apten API will send an HTTP request to the URL you provided
with JSON data whenever the event occurs.

You can also provide a secret key when configuring a webhook. The secret key is used to sign the
webhook request, so you can verify that the request is coming from the Apten API. You can learn more
about verifying webhooks in the [Verifying Webhooks](/webhooks/verification) section.

## Lead webhooks and webchat webhooks

Apten provides two parallel webhook domains:

* **Lead webhooks** fire on the SMS, email, and voice lead lifecycle. They identify a lead by `leadId` / `phone` and carry a `channel` field (`sms`, `email`, `call`, or `manual`).
* **Webchat webhooks** fire on events that occur inside a webchat session. They identify a session by `sessionId` and carry `profile` and optional `origin` fields instead of `channel`.

Both domains are configured in the same [Developer Portal](https://platform.attent.app/developer), share the same HMAC-SHA256 signing scheme, and use the same `{ event, timestamp, data }` envelope, but they are logically distinct event feeds — subscribe to each event you care about.

## Lead Webhook Events

The following events fire on the lead lifecycle:

* [**Lead Tagged**](/webhooks/lead-tagged): This event occurs when a lead is tagged by Apten.
* [**Lead Additional Info Updated**](/webhooks/lead-additional-info-updated): This event occurs when a lead's `additionalInfo` fields change.
* [**Notification Created**](/webhooks/notification-created): This event occurs when a new notification is created by Apten.
* [**Message Received**](/webhooks/message-received): This event occurs when a message is received from a lead.
* [**Message Sent**](/webhooks/message-sent): This event occurs when a message is sent to a lead.
* [**Call Completed**](/webhooks/call-completed): This event occurs when a call is finished.
* [**Call Attempted**](/webhooks/call-attempted): This event occurs when an outbound call attempt is made, regardless of outcome.
* [**Call Transferred**](/webhooks/call-transferred): This event occurs when a call is transferred to a human agent.
* [**Call Transfer Connected**](/webhooks/call-transfer-connected): This event occurs when a warm transfer successfully bridges a human agent to the lead.
* [**Transfer Fallback Triggered**](/webhooks/transfer-fallback-triggered): This event occurs when a warm transfer fallback is dispatched after the primary agent misses.
* [**Agent Missed Transfer**](/webhooks/agent-missed-transfer): This event occurs when a call transfer to a human agent is missed.
* [**Guardrail Triggered**](/webhooks/guardrail-triggered): This event occurs when a guardrail is triggered during a conversation.
* [**Opt Out**](/webhooks/opt-out): This event occurs when a lead opts out of messaging.
* [**Opt In**](/webhooks/opt-in): This event occurs when a lead re-subscribes after previously opting out.

## Webchat Webhook Events

The following events fire on webchat sessions:

* [**Session Started**](/webhooks/webchat/session-started): This event occurs when a new webchat session is created.
* [**Message Received**](/webhooks/webchat/message-received): This event occurs when a visitor sends a message in webchat.
* [**Message Sent**](/webhooks/webchat/message-sent): This event occurs when the AI or a human agent sends a message in webchat.
* [**Contact Form Submitted**](/webhooks/webchat/contact-form-submitted): This event occurs when a visitor submits the webchat contact form.
* [**Session Converted**](/webhooks/webchat/session-converted): This event occurs when a webchat session is converted into a lead.
* [**Guardrail Triggered**](/webhooks/webchat/guardrail-triggered): This event occurs when a guardrail is triggered on a webchat message.
* [**Call Transferred**](/webhooks/webchat/call-transferred): This event occurs when a transfer call happens in a webchat session.

## Webhook Event Schema Body

Webhook endpoints will be called with the following JSON body:

```json theme={null}
{
  "event": "eventName", // Event name
  "timestamp": "2024-01-15T14:30:00Z", // Datetime string in ISO 8601 format
  "data": {} // Event-specific details
}
```