⚡Webhooks

Webhooks let you receive real-time notifications when events happen in Ring Tonic. Instead of polling our API, we push data to your server the moment a call comes in, a recording is ready, or a lead is qualified.

Webhooks are available on the Agency plan only. Perfect for CRM integrations like GoHighLevel, HubSpot, and Zapier.

---

Available Events

Event	Description
call.started	Fires when a call starts ringing
call.completed	Fires when a call ends (includes duration and status)
call.missed	Fires when a call is missed (busy, no-answer, failed)
recording.available	Fires when call recording is ready
transcription.available	Fires when call transcription is complete
lead.qualified	Fires when you qualify a lead in the dashboard
voicemail.received	Fires when a caller leaves a voicemail
voicemail.transcribed	Fires when voicemail transcription is complete

---

Creating a Webhook Endpoint

Create a webhook endpoint form

1. Go to Webhooks in the main navigation

2. Click Add Endpoint

3. Fill in the endpoint details:

   • Name: A friendly name (e.g., "GoHighLevel Integration")

   • Endpoint URL: Your HTTPS URL that will receive the webhook

   • Events: Select which events to subscribe to

4. Click Create Endpoint

HTTPS Required: Your endpoint URL must use HTTPS. HTTP URLs are not accepted for security reasons.

---

Signing Secret

Each webhook endpoint has a unique signing secret (e.g., whsec_abc123...). Use this to verify that requests are genuinely from Ring Tonic.

We sign every webhook request using HMAC-SHA256. The signature is included in the Signature header.

Verifying Signatures (PHP Example)

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_SIGNATURE'];
$secret = 'whsec_your_secret_here';

$expectedSignature = hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expectedSignature, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

// Process the webhook...

Pro Tip: You can regenerate your signing secret anytime from the Edit page if you suspect it's been compromised.

---

Testing Your Endpoint

1. Go to your webhook endpoint's detail page

2. Click Send Test

3. Select an event type from the dropdown (only events you're subscribed to are shown)

4. Click Send Test to dispatch a sample webhook with realistic data

5. Check your server logs for the test payload

6. Verify the delivery status in the Recent Deliveries table

Realistic Sample Data: Test webhooks include sample data that matches the real payload structure for each event type. This helps you test your integration logic before real calls come in.

Test a webhook endpoint

---

Payload Examples

All webhooks follow the same structure with event-specific data in the data object.

call.completed

{
  "event": "call.completed",
  "created_at": "2025-01-15T14:30:00+00:00",
  "data": {
    "call_log_id": 12345,
    "twilio_call_sid": "CA1234567890abcdef",
    "from_number": "[phone]",
    "caller_name": "John Smith",
    "tracking_number": "[phone]",
    "tracking_number_name": "Google Ads - Main",
    "campaign_id": 42,
    "campaign_name": "Google Ads Campaign",
    "status": "completed",
    "duration": 145,
    "caller_location": {
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "zip": "94102"
    },
    "is_first_time_caller": true,
    "utm_source": "google",
    "utm_medium": "cpc",
    "started_at": "2025-01-15T14:27:35+00:00"
  }
}

recording.available

Includes all base fields plus:

{
  "event": "recording.available",
  "data": {
    "recording_url": "https://api.twilio.com/recordings/RE123...",
    // ... all base call data
  }
}

transcription.available

Includes all base fields plus:

{
  "event": "transcription.available",
  "data": {
    "transcription": "Hi, I'm calling about your services...",
    "transcription_confidence": 0.95,
    // ... all base call data
  }
}

lead.qualified

Includes all base fields plus:

{
  "event": "lead.qualified",
  "data": {
    "lead_status": "qualified",
    "qualification_reason": "Customer interested in premium package",
    "qualification_confidence": 0.89,
    "deal_value": 2500.00,
    "qualified_at": "2025-01-15T15:00:00+00:00",
    // ... all base call data
  }
}

voicemail.received

Fires when a caller leaves a voicemail. Includes all base fields plus:

{
  "event": "voicemail.received",
  "data": {
    "voicemail": {
      "recording_url": "https://api.twilio.com/recordings/RE456...",
      "duration": 15
    },
    // ... all base call data
  }
}

voicemail.transcribed

Fires when a voicemail transcription is complete. Includes all base fields plus:

{
  "event": "voicemail.transcribed",
  "data": {
    "voicemail": {
      "recording_url": "https://api.twilio.com/recordings/RE456...",
      "duration": 15,
      "transcription": "Hi, this is John. I missed your call and wanted to learn more about your services. Please call me back when you get a chance. Thanks!",
      "transcribed_at": "2025-01-15T14:32:00+00:00"
    },
    // ... all base call data
  }
}

---

Delivery & Retries

Ring Tonic automatically retries failed deliveries with exponential backoff. You can monitor delivery status from the endpoint detail page:

• Success: Your server returned 2xx

• Retrying: Delivery failed, retrying automatically

• Failed: All retry attempts exhausted

Circuit Breaker: After 10 consecutive failures, the endpoint is automatically disabled to prevent further issues. Re-enable it from the detail page after fixing the problem.

Manual Retry

For failed deliveries, click the Retry button in the delivery detail modal to manually queue a retry.

Manual retry a webhook delivery

---

Integration Example: GoHighLevel

This example shows how to connect Ring Tonic with GoHighLevel (GHL) to automatically create contacts and trigger automations when calls come in.

How It Works

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│  Caller     │──────│  Ring Tonic │──────│  GHL        │
│  dials      │      │  tracks &   │      │  creates    │
│  tracking # │      │  attributes │      │  contact &  │
│             │      │  the call   │      │  triggers   │
│             │      │             │      │  automation │
└─────────────┘      └─────────────┘      └─────────────┘

1. Ring Tonic handles inbound calls - Your tracking number lives in Ring Tonic. We record the call and attribute the source (Google Ads, SEO, etc.) which GHL can't do natively.

2. Ring Tonic pushes data to GHL - When a call ends, we fire a webhook to GHL with full call details and attribution data.

3. GHL automations fire - Your GHL workflow creates the contact, adds tags (e.g., "PPC Lead"), and triggers SMS/email follow-ups.

1

Create the GHL Workflow

• In GoHighLevel, go to Automation → Workflows

• Click Create Workflow → Start from Scratch

• Click Add New Trigger → Select Inbound Webhook

• Copy the generated Webhook URL (you'll need this for Ring Tonic)

• Click Save Trigger

For more details, see GHL's Inbound Webhook documentation.

2

Create the Ring Tonic Endpoint

• In Ring Tonic, go to Webhooks → Add Endpoint

• Enter a name: GoHighLevel Integration

• Paste the GHL Webhook URL from Step 1

• Select events: call.completed, call.missed (and optionally recording.available)

• Click Create Endpoint

3

Test the Connection

• In Ring Tonic, click Send Test on your new endpoint

• Back in GHL, your workflow should show the test data received

• You can now map the incoming fields to GHL contact fields

4

Build the GHL Workflow

After the Inbound Webhook trigger, add these actions:

• Create/Update Contact

  • Phone: {{data.from_number}}

  • First Name: (optional, or use a placeholder)

  • Tags: Add tags based on campaign, e.g., {{data.campaign_name}}

• Add to Campaign/Sequence (optional)

  • Enroll the contact in a follow-up sequence

• Send SMS (optional)

  • "Thanks for calling! We'll be in touch shortly."

Field Mapping Reference

Ring Tonic Field	GHL Use Case
data.from_number	Contact Phone
data.caller_name	Contact Name
data.campaign_name	Contact Tag or Custom Field
data.utm_source	Lead Source
data.utm_medium	Custom Field (e.g., "ppc", "organic")
data.caller_location.city	Contact City
data.caller_location.state	Contact State
data.is_first_time_caller	Tag: "New Caller" vs "Repeat Caller"
data.duration	Custom Field (call length in seconds)
data.recording_url	Custom Field (link to recording)

Pro Tip: Use is_first_time_caller to branch your workflow. Send a welcome message to new callers and a "thanks for calling again" to repeat callers.

---

Common Questions

What HTTP method is used?

All webhooks are sent as POST requests with a JSON body. The Content-Type header is set to application/json.

How many times will you retry a failed delivery?

Each delivery is retried up to 3 times with exponential backoff. After all retries are exhausted, that delivery is marked as failed. If 10 consecutive deliveries fail (each after exhausting retries), the endpoint is automatically disabled via circuit breaker.

How quickly are webhooks sent?

Webhooks are dispatched immediately when the event occurs, typically within seconds.

What response should my server return?

Return any 2xx status code (200, 201, 204, etc.) to acknowledge receipt. We ignore the response body.

How long do you store delivery logs?

Delivery logs are retained for 30 days.

Can I have multiple endpoints for the same event?

Yes, you can create multiple endpoints subscribing to the same events. Each will receive the webhook independently.