Webooks for Virtual Numbers

Overview

LimePhone's Virtual Number Webhooks allow you to receive real-time updates on calls, SMS, voicemails, and status changes associated with your virtual numbers. This feature enables seamless integration with your CRM, helpdesk, or other business tools for better workflow automation.

You can configure webhooks for each virtual number in your LimePhone account via: ➡ Dashboard > Numbers > Manage > Webhooks

---

Key Features

✅ Event-Based Notifications – Get instant updates on incoming/missed calls, SMS, and voicemails. ✅ Number-Specific Webhooks – Configure unique webhook URLs for different virtual numbers. ✅ Customizable Data Capture – Include call details, customer info, timestamps, and more. ✅ Secure and Reliable – Authenticate webhook requests with HMAC signatures and HTTPS encryption.

---

Supported Events

Virtual Number Webhooks can trigger on the following events:

Event	Description
incoming_call	Triggered when a call is received.
missed_call	Triggered when a call goes unanswered.
call_completed	Triggered when a call is successfully completed.
voicemail_received	Triggered when a voicemail is left.
sms_sent	Triggered when an SMS is sent from the virtual number.
sms_received	Triggered when an SMS is received.
call_status_update	Triggered when a call’s status changes (e.g., ringing, answered, failed).

---

How to Set Up Virtual Number Webhooks

Step 1: Configure Webhook for a Virtual Number

1. Log in to LimePhone at app.limephone.io.

2. Go to Dashboard > Numbers.

3. Click Manage next to the virtual number you want to configure.

4. Select the Webhooks tab.

5. Click "Create Webhook" and enter:

   • Webhook URL – The endpoint where LimePhone will send data.

   • Event Types – Select which events will trigger the webhook.

   • Security Settings – Enable authentication to verify webhook requests.

6. Click Save to activate the webhook.

---

Step 2: Test Your Webhook

1. Click "Test Webhook" in the LimePhone dashboard.

2. Send a sample payload to your configured endpoint.

3. Verify that your system receives and processes the data correctly.

4. Check the Webhook Logs in LimePhone for detailed request history.

---

Step 3: Manage Webhooks

• Edit Webhooks – Modify the webhook URL, event triggers, or security settings.

• Delete Webhooks – Remove unused webhooks to optimize performance.

• Monitor Logs – View webhook logs to debug and track requests.

---

Webhook Request Format

HTTP Request

LimePhone sends a POST request to your webhook URL whenever an event occurs.

Example Endpoint: POST https://yourapp.com/webhook-endpoint

Request Headers

Header	Value	Description
Content-Type	application/json	Specifies the payload format.
Authorization	Bearer {token}	API token for authentication.
X-LimePhone-Signature	{hash}	HMAC-SHA256 signature for request validation.

---

Request Payloads (Examples)

Incoming Call Event

jsonCopyEdit{
  "event": "incoming_call",
  "call_id": "123456",
  "virtual_number": "[phone]",
  "caller_number": "[phone]",
  "timestamp": "2025-01-30T14:00:00Z",
  "call_status": "ringing"
}

Missed Call Event

jsonCopyEdit{
  "event": "missed_call",
  "call_id": "789012",
  "virtual_number": "[phone]",
  "caller_number": "[phone]",
  "timestamp": "2025-01-30T14:05:00Z",
  "call_status": "missed"
}

Voicemail Received Event

jsonCopyEdit{
  "event": "voicemail_received",
  "call_id": "567890",
  "virtual_number": "[phone]",
  "caller_number": "[phone]",
  "voicemail_url": "https://limephone.io/voicemails/123456",
  "timestamp": "2025-01-30T14:10:00Z"
}

SMS Sent Event

jsonCopyEdit{
  "event": "sms_sent",
  "message_id": "234567",
  "virtual_number": "[phone]",
  "recipient_number": "[phone]",
  "message_content": "Your appointment is confirmed!",
  "timestamp": "2025-01-30T14:15:00Z"
}

SMS Received Event

jsonCopyEdit{
  "event": "sms_received",
  "message_id": "345678",
  "virtual_number": "[phone]",
  "sender_number": "[phone]",
  "message_content": "Hi, I’d like more details.",
  "timestamp": "2025-01-30T14:20:00Z"
}

---

Response Handling

Your application should respond with a 200 OK status code to acknowledge the webhook. If LimePhone doesn’t receive a success response, it will retry according to the following schedule:

• Retry after 1 minute.

• Retry after 5 minutes.

• Retry after 15 minutes.

• Retry after 30 minutes.

---

Securing Your Webhooks

1. Verify the Request Signature

   • Use the X-LimePhone-Signature header to validate the request.

   • The signature is an HMAC-SHA256 hash of the request body using your webhook secret.

2. Use HTTPS

   • Ensure your webhook URL uses HTTPS for secure data transmission.

3. Validate Input Data

   • Sanitize and validate all incoming webhook data before processing.

---

Use Cases

✔ CRM Integration: Automatically log calls, messages, and voicemails in your CRM. ✔ Real-Time Alerts: Send missed call or voicemail notifications via Slack or email. ✔ Call Routing Automation: Route calls based on virtual number, caller ID, or predefined logic. ✔ SMS Follow-Ups: Automate SMS responses based on received messages. ✔ Analytics & Reporting: Track virtual number activity for call and message insights. ✔ AI-Powered Workflows: Use webhooks to trigger AI-based lead qualification or automated workflows.

---

Best Practices

✅ Test Before Deployment: Use the "Test Webhook" feature to ensure proper integration. ✅ Monitor Webhook Logs: Regularly check webhook logs for request history and errors. ✅ Implement Retry Handling: Ensure your system can handle duplicate or retried requests. ✅ Optimize API Response Times: Your webhook endpoint should respond within 5 seconds to prevent retries.

---

Need Help?

For support, reach out to [e-mail] or visit our documentation at docs.limephone.io.