Skip to main content

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.

​
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. 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 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, 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: This event occurs when a lead is tagged by Apten.
  • Notification Created: This event occurs when a new notification is created by Apten.
  • Message Received: This event occurs when a message is received from a lead.
  • Message Sent: This event occurs when a message is sent to a lead.
  • Call Completed: This event occurs when a call is finished.
  • Call Attempted: This event occurs when an outbound call attempt is made, regardless of outcome.
  • Call Transferred: This event occurs when a call is transferred to a human agent.
  • Call Transfer Connected: This event occurs when a warm transfer successfully bridges a human agent to the lead.
  • Agent Missed Transfer: This event occurs when a call transfer to a human agent is missed.
  • Guardrail Triggered: This event occurs when a guardrail is triggered during a conversation.
  • Opt Out: This event occurs when a lead opts out of messaging.

​
Webchat Webhook Events

The following events fire on webchat sessions:
  • Session Started: This event occurs when a new webchat session is created.
  • Message Received: This event occurs when a visitor sends a message in webchat.
  • Message Sent: This event occurs when the AI or a human agent sends a message in webchat.
  • Contact Form Submitted: This event occurs when a visitor submits the webchat contact form.
  • Session Converted: This event occurs when a webchat session is converted into a lead.
  • Guardrail Triggered: This event occurs when a guardrail is triggered on a webchat message.
  • 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: 
{
  "event": "eventName", // Event name
  "timestamp": "2024-01-15T14:30:00Z", // Datetime string in ISO 8601 format
  "data": {} // Event-specific details
}