← All posts
Aircall

Aircall Integration Explained

Charles Lee · August 25, 2025

Introduction

Setting up webhook triggers in Aircall allows you to send real-time data to your external systems based on specific events. This is essential for building custom integrations and automating workflows.

What Events Can Trigger a Webhook?

You can receive notifications for a wide range of events, including:

  • User events (e.g., user.created)
  • Number events (e.g., number.closed)
  • Message events (e.g., sms.sent)
  • Call events (e.g., call.ringing_on_agent)
  • Contact events (e.g., contact.updated)
  • Conversation Intelligence events (e.g., sentiment.created)

Two Ways to Set Up Webhooks This guide covers the two methods for configuring webhooks in Aircall:

  1. Via the Aircall Dashboard: A simple, no-code approach.
  2. Via the Public API: A more flexible method for developers.

🖥️ Method 1: Via the Aircall Dashboard

This is the quickest way to get started with Aircall webhooks.

  1. From the Aircall dashboard, navigate to the Integrations page and select “Webhook integration”.
  2. Click “Install”.
  3. (Optional) Give your webhook a custom name to easily identify it later.
  4. In the URL field, enter the endpoint URL from your web server.

    Important Limitation You can only provide a single URL, and you cannot customize the request headers for authentication. Any necessary tokens must be included as query parameters in the URL itself.

  5. Toggle the switches for the events you want to subscribe to. By default, all events are turned on.
  6. Click “Save” to finish the configuration.

👨‍💻 Method 2: Via the Public API

The Aircall Public API allows for programmatic creation, updating, and deletion of webhooks. This is ideal for developers and more complex integrations. Aircall supports two authentication methods: OAuth (for tech partners) and Basic Auth (for customers). We’ll focus on the more common customer use case with Basic Auth.

1. Get Your API Credentials (Basic Auth)

  1. In your Aircall dashboard, go to your Company’s Settings page.
  2. In the API Keys section, click “Add a new API key”.
  3. This will generate an api_id and api_token. In Basic Auth, the api_id serves as your username and the api_token is your password.

2. Create the Webhook with an API Call

You can use a tool like Postman to make the API request.

  1. Create a new HTTP request with the POST method.
  2. Set the URL to https://api.aircall.io/v1/webhooks.
  3. Set the Content-Type header to application/json.
  4. In the Authorization tab, select Basic Auth and enter your api_id as the username and api_token as the password.
  5. In the Body of the request, provide a JSON object specifying the webhook’s details:
{
  "custom_name": "My Custom Workflow",
  "url": "https://my-server.example.com/webhooks/contacts",
  "events": [
    "contact.created",
    "contact.updated",
    "contact.deleted"
  ]
}
  1. Send the request. A successful creation will return a 201 Created status code and the details of your new webhook.
{
  "webhook": {
    "webhook_id": "c2501111-8a69-4342-bb34-bcd6cfe564ab",
    "direct_link": "https://api.aircall.io/v1/webhooks/26316",
    "created_at": "2020-03-24T19:51:24.000Z",
    "url": "https://my-server.example.com/webhooks/contacts",
    "active": true,
    "events": [
      "contact.created",
      "contact.updated",
      "contact.deleted"
    ],
    "token": "df76g76dpziygs567f0"
  }
}

✅ Best Practices & Key Notes

  • Use HTTPS: Always use a secure HTTPS URL for your webhook endpoint.
  • Return 200 OK: Your server should promptly return a 200 OK status code to acknowledge receipt of the webhook.
  • Asynchronous Processing: Handle any time-consuming tasks in an asynchronous queue to avoid timeouts.
  • Re-enable Deactivated Webhooks: Monitor for and automatically re-enable any webhooks that get deactivated due to repeated failures.

Difference Between call.hungup and call.ended

This is a common point of confusion. The two events serve different purposes:

  • call.hungup: This event fires immediately when a call ends, even if all the data (like recordings) isn’t ready. It’s best for real-time applications like dashboards.
  • call.ended: This event fires after all call data is gathered (usually ~30 seconds after the call ends). It’s best for archiving and processing complete call records.

📚 References