Webhooks

Updated on October 10, 2025

Our Webhook integration allows you to receive real-time HTTP notifications about events happening within your telephony service. By subscribing to specific events, you can build custom applications, automate workflows, and synchronize data with your own systems the moment something happens. 🚀

For example, you can use webhooks to:

  • Update a customer’s record in your CRM the instant a call is initiated.
  • Log detailed call information into your own database when a call ends.
  • Analyze call transcripts in real-time for sentiment or keyword-spotting.
  • Trigger alerts in a messaging platform like Slack for missed calls or errors.

Configuration

Setting up your webhook integration is straightforward. You can find the configuration panel under Settings > Integrations > Custom Webhook.

  1. Enable Integration: First, toggle the Enabled switch to activate the webhook service.
  2. Webhook URL: Enter the URL of your server endpoint that will listen for and process the incoming webhook requests. Your application must be configured to receive HTTP POST requests at this URL.
  3. Additional Headers (Optional): If your endpoint requires authentication, you can add custom HTTP headers. This is useful for passing API keys or authorization tokens.
  4. Subscribe to Events: Select the specific events you want to receive notifications for.
  5. Save: Click the Save button to apply your changes.

Payload Structure

All webhook requests follow a consistent JSON structure. Your endpoint will receive a POST request with the following top-level keys:

  • event_type: (String) The name of the event that was triggered.
  • timestamp_utc: (Integer) A Unix timestamp of when the event occurred.
  • payload: (Object) An object containing the specific data for the event.
  • is_test: (Boolean) This will be true if the event was triggered by the “Test Webhook Integration” button.

Event Types and Examples

Below are the details and example payloads for each event you can subscribe to. The direction field in the payload is important as it indicates whether the call is inbound or outbound.

#call_initiated

Sent when a new call (inbound or outbound) is started. This is the very first event in a call’s lifecycle.

JSON

{
  "event_type": "call_initiated",
  "timestamp_utc": 1760084505,
  "payload": {
    "call_id": 1,
    "from": "+905555555555",
    "to": "+905555555554",
    "direction": "outbound",
    "source": "salprebox:SALPRE_AABBCCDD"
  },
  "is_test": true
}

#call_ringing

Sent when an inbound call starts ringing for the agent or an outbound call is connecting to the destination number.

JSON

{
  "event_type": "call_ringing",
  "timestamp_utc": 1760084555,
  "payload": {
    "from": "+905555555555",
    "to": "+905555555554",
    "source": "salprebox:SALPRE_AABBCCDD",
    "direction": "outbound",
    "call_id": 1
  },
  "is_test": true
}

#call_answered

Sent as soon as the call is answered by the receiving party.

JSON

{
  "event_type": "call_answered",
  "timestamp_utc": 1760084576,
  "payload": {
    "from": "+905555555555",
    "to": "+905555555554",
    "source": "salprebox:SALPRE_AABBCCDD",
    "direction": "outbound",
    "call_id": 1
  },
  "is_test": true
}

#transcript

Sent during an active call as speech is being transcribed. This webhook provides a live, partial transcript of the conversation as it happens, making it ideal for real-time analysis.

JSON

{
  "event_type": "transcript",
  "timestamp_utc": 1760084622,
  "payload": {
    "call": {
      "id": 1,
      "from": "+905555555555",
      "to": "+905555555554",
      "source": "salprebox:SALPRE_AABBCCDD",
      "direction": "outbound"
    },
    "type": "customer",
    "transcript": "Hello, how are you?",
    "timestamp_utc": "111111"
  },
  "is_test": true
}

#call_ended

Sent after a call is terminated by either party. This payload is the most comprehensive, as it contains the complete, final transcript of the entire conversation.

JSON

{
  "event_type": "call_ended",
  "timestamp_utc": 1760084597,
  "payload": {
    "from": "+905555555555",
    "to": "+905555555554",
    "direction": "outbound",
    "source": "salprebox:SALPRE_AABBCCDD",
    "call_id": 1,
    "transcript": [
      {
        "type": "ai",
        "message": "Greeting message"
      },
      {
        "type": "customer",
        "message": "customer message 1",
        "utc_timestamp": "111111"
      },
      {
        "type": "ai",
        "message": "Ai response 1",
        "utc_timestamp": "111111"
      }
    ]
  },
  "is_test": true
}

#error

Sent if an error occurs at any point during the call (e.g., connection failed, configuration issue).

JSON

{
  "event_type": "error",
  "timestamp_utc": 1760084656,
  "payload": {
    "call": {
      "id": 1,
      "from": "+905555555555",
      "to": "+905555555554",
      "source": "salprebox:SALPRE_AABBCCDD",
      "direction": "outbound"
    },
    "error_message": "Error message"
  },
  "is_test": true
}

Testing Your Integration

To ensure your endpoint is configured correctly, use the Test Webhook Integration button. This will send a pre-defined example payload to your specified Webhook URL, which will have the is_test flag set to true.

Your server should respond with a 200 OK status code to acknowledge that it has successfully received the request. If we do not receive a 200 OK response, we will consider the delivery a failure.

Next

Integrations
Read
Membership
Read