⚡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

Creating a Webhook Endpoint

Go to Webhooks in the main navigation
Click Add Endpoint
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
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

Go to your webhook endpoint's detail page
Click Send Test
Check your server logs for the test payload
Verify the delivery status in the Recent Deliveries table

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": "+14155551234",
    "tracking_number": "+18005551234",
    "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
  }
}

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.

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 │
└─────────────┘      └─────────────┘      └─────────────┘

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.
Ring Tonic pushes data to GHL - When a call ends, we fire a webhook to GHL with full call details and attribution data.
GHL automations fire - Your GHL workflow creates the contact, adds tags (e.g., "PPC Lead"), and triggers SMS/email follow-ups.

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.

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

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

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.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.

PreviousAnalytics NextPort Existing Numbers

Last updated 3 days ago