# Outbound Webhooks

### **Overview**

LimeCall's Outbound Webhook feature enables you to send real-time notifications and data from LimeCall to external systems whenever specific events occur. This allows you to integrate LimeCall seamlessly with your existing tools, such as CRMs, marketing automation platforms, or custom applications, to improve workflow automation and efficiency.

***

### **Key Features**

* **Event-Driven Notifications:** Trigger webhooks on key events like missed calls, voicemails, SMS replies, or call status updates.
* **Real-Time Data Transfer:** Send data instantly to external systems for processing or storage.
* **Customizable Payloads:** Include essential fields such as call details, customer information, and timestamps.
* **Secure Communication:** Authenticate webhook requests with a unique signature and HTTPS encryption.

***

### **Supported Events**

You can configure outbound webhooks to trigger on the following events:

1. **Missed Call:** Notification when a call goes unanswered.
2. **Call Completed:** Data sent after a call is completed.
3. **Voicemail Received:** Notification when a voicemail is left by a caller.
4. **SMS Received:** Triggered when a new SMS is received.
5. **Call Status Update:** Notification for changes in call status (e.g., ringing, answered, failed).

***

### **How It Works**

1. **Event Occurs in LimeCall:** A specific event, such as a missed call or voicemail, triggers the webhook.
2. **Webhook Sends Data:** LimeCall sends a POST request with the event data to your configured endpoint.
3. **Process Data Externally:** Your application processes the webhook data and performs an action, such as logging the event, updating a CRM, or triggering an alert.

***

### **How to Set Up Outbound Webhooks**

#### **Step 1: Configure the Webhook**

1. **Log in to LimeCall Dashboard:**\
   Navigate to **Settings > Webhooks > Outbound Webhooks**.
2. **Create a New Webhook:**
   * Click on **"Create Outbound Webhook"**.
   * Provide a **Webhook Name** (e.g., "CRM Integration").
   * Enter the **Webhook URL** (your application endpoint that will receive the data).
   * Select the **Event Type(s)** you want to trigger the webhook (e.g., Missed Call, Voicemail Received).
   * Add optional filters to limit the data sent based on conditions (e.g., calls from specific numbers).
3. **Save the Webhook Configuration:**\
   Click **Save Webhook** to activate the webhook.

***

#### **Step 2: Test the Webhook**

1. **Send a Test Request:**\
   Use the **"Test Webhook"** feature in the LimeCall dashboard to send a sample payload to your endpoint.
2. **Verify Your Endpoint:**\
   Confirm that your application successfully receives and processes the data.
3. **Check Logs:**\
   Review the **Webhook Logs** in the LimeCall dashboard to ensure proper configuration.

***

#### **Step 3: Monitor and Manage Webhooks**

* **View Logs:** Check webhook logs for recent requests, payload details, and response statuses.
* **Edit Webhooks:** Update webhook settings, such as the endpoint URL or triggered events, from the dashboard.
* **Delete Webhooks:** Remove inactive or obsolete webhooks to maintain system cleanliness.

***

### **Request Details**

#### **HTTP Request**

LimeCall sends a POST request to your configured endpoint for each event.

**Example Endpoint:**\
`POST https://yourapplication.com/webhook-endpoint`

#### **Request Headers**

| **Header**             | **Value**          | **Description**                                           |
| ---------------------- | ------------------ | --------------------------------------------------------- |
| `Content-Type`         | `application/json` | Specifies the format of the payload.                      |
| `Authorization`        | `Bearer {token}`   | Token for authenticating the request.                     |
| `X-LimeCall-Signature` | `{hash}`           | HMAC-SHA256 signature for verifying request authenticity. |

#### **Request Body**

The webhook sends event-specific data in the payload. Below are sample payloads for different events:

**Missed Call Event**

```json
jsonCopyEdit{
  "event": "missed_call",
  "call_id": "123456",
  "caller_number": "+1234567890",
  "callee_number": "+0987654321",
  "timestamp": "2025-01-30T15:00:00Z",
  "team_id": "team_001",
  "status": "missed"
}
```

**Voicemail Received Event**

```json
jsonCopyEdit{
  "event": "voicemail_received",
  "call_id": "789012",
  "caller_number": "+1234567890",
  "callee_number": "+0987654321",
  "voicemail_url": "https://limecall.io/voicemails/123456",
  "timestamp": "2025-01-30T15:05:00Z",
  "team_id": "team_002"
}
```

**SMS Received Event**

```json
jsonCopyEdit{
  "event": "sms_received",
  "message_id": "567890",
  "sender_number": "+1234567890",
  "receiver_number": "+0987654321",
  "message_content": "Hello, I’m interested in your services.",
  "timestamp": "2025-01-30T15:10:00Z"
}
```

***

### **Response**

Your application should respond with a `200 OK` status code to acknowledge receipt of the webhook. If LimeCall receives an error or no response, it will retry the request according to the following schedule:

* Retry after 1 minute.
* Retry after 5 minutes.
* Retry after 15 minutes.
* Retry after 30 minutes.

***

### **Securing Your Webhook**

1. **Verify the Signature:** Use the `X-LimeCall-Signature` header to validate that the request originated from LimeCall. The signature is an HMAC-SHA256 hash of the request body using your webhook secret.
2. **Use HTTPS:** Ensure your webhook endpoint uses HTTPS to encrypt data in transit.
3. **Validate Input:** Sanitize and validate all incoming data before processing.

***

### **Best Practices**

* **Test Thoroughly:** Use the "Test Webhook" feature to verify your setup before enabling it for production.
* **Log Webhook Activity:** Maintain a log of received webhooks for debugging and auditing.
* **Set Up Fallbacks:** Implement fallback mechanisms in your system to handle webhook delivery failures.
* **Monitor Performance:** Regularly review webhook logs in the LimeCall dashboard to identify and resolve issues.

***

### **Need Assistance?**

If you encounter any issues or have questions, feel free to contact our support team at **support@limecall.io**
