> For the complete documentation index, see [llms.txt](https://help.ringtonic.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.ringtonic.app/guides/webhooks.md).

# Webhooks

<figure><img src="https://2905537093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXSbXRgC7knjpaMCHwuKc%2Fuploads%2Fgit-blob-0ef72a30ea345444e49c24e08352476fc947e487%2FXnapper-2025-12-01-23.11.54.png?alt=media" alt=""><figcaption></figcaption></figure>

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.

{% hint style="info" %}
Webhooks are available on the **Agency plan** only. Perfect for CRM integrations like GoHighLevel, HubSpot, and Zapier.
{% endhint %}

***

### Available Events

| Event                        | Description                                                                                                                                                                              |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `call.started`               | Fires when a call starts ringing                                                                                                                                                         |
| `call.completed`             | Fires when an answered call ends (includes duration and status)                                                                                                                          |
| `call.missed`                | Fires when a call ends unanswered (no answer, busy, failed, or the caller hung up first)                                                                                                 |
| `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                                                                                                                                           |
| `form.submitted`             | Fires when a visitor submits a form captured by [Form Submissions](https://help.ringtonic.app/guides/form-submissions.md)                                                                |
| `contact.stage_changed`      | Fires when a contact moves to a new pipeline stage                                                                                                                                       |
| `conversion.recorded`        | Fires when a conversion is recorded on a contact                                                                                                                                         |
| `call.blocked`               | Fires when a blocked number attempts to call                                                                                                                                             |
| `voicemail.received`         | Fires when a caller leaves a voicemail                                                                                                                                                   |
| `voicemail.transcribed`      | Fires when voicemail transcription is complete                                                                                                                                           |
| `appointment.booked`         | Fires when an appointment is booked                                                                                                                                                      |
| `appointment.rescheduled`    | Fires when an appointment's time is changed                                                                                                                                              |
| `appointment.cancelled`      | Fires when an appointment is cancelled                                                                                                                                                   |
| `appointment.status_changed` | Fires when an appointment is marked completed / no-show, or reverted                                                                                                                     |
| `sms.received`               | Fires when someone texts one of your tracking numbers. See [Receiving Texts](https://help.ringtonic.app/guides/phone-numbers.md#receiving-texts) for which numbers and the hourly limits |

Appointment events fire for both AI-booked and manually-booked appointments — see [Appointments](https://help.ringtonic.app/guides/appointments.md). For when each contact and form event fires, see [Webhook Companions](https://help.ringtonic.app/guides/crm-api.md#webhook-companions).

{% hint style="info" %}
**Each finished call sends one outcome event:** `call.completed` when someone answered, `call.missed` when nobody did. Three calls work differently:

* A caller who leaves a voicemail sends `voicemail.received` instead. If you follow up on missed calls, subscribe to both.
* A call stopped by your Spam Filter sends no outcome event, only `call.started`.
* A call that [Spam Screening](https://help.ringtonic.app/guides/spam-screening.md) marks as suspected spam sends no outcome event and no `recording.available`. If you mark it **Not spam**, they are sent then.
  {% endhint %}

{% hint style="warning" %}
**`call.started` fires before any screening.** It is sent the moment a call reaches your tracking number, which is before the spam filter has had a chance to check whether the caller is a real person — so robocalls trigger it too.

If you only want your CRM to hear about verified callers, put a **Webhook** node after the Spam Filter in a call flow instead. It runs only on the passed branch, and it can send the same attribution the caller arrived with. See [Send only real callers to your CRM](https://help.ringtonic.app/guides/call-flow-builder.md#recipes-real-world-flow-patterns).
{% endhint %}

{% hint style="info" %}
**Forms and webhooks:** On a campaign with [Form Submissions](https://help.ringtonic.app/guides/form-submissions.md) on, every captured submission sends `form.submitted`, with the mapped fields and the other fields [Auto-detect](https://help.ringtonic.app/guides/form-submissions.md#auto-detect-fields) captured. Form Attribution is separate: it adds attribution data (UTMs, click IDs, `ga_client_id`, `ga_session_id`) to your website's forms as hidden fields, which go to *your* form handler (HubSpot, Squarespace, your CRM, etc.), not to Ring Tonic.
{% endhint %}

***

### Attribution Fields in Call Payloads

Every call payload includes a nested `visitor_session` object with the full attribution context captured by the website tracker script when the caller's session was created.

{% hint style="warning" %}
**Where to find GA fields:** `ga_client_id` and `ga_session_id` live inside `data.visitor_session`, **not** at the top level of `data`. Only `utm_source` and `utm_medium` are promoted to the top level for convenience.
{% endhint %}

| Field                                   | Description                                    |
| --------------------------------------- | ---------------------------------------------- |
| `data.visitor_session.gclid`            | Google Ads click ID                            |
| `data.visitor_session.gbraid`           | Google iOS app click ID                        |
| `data.visitor_session.wbraid`           | Google privacy-restricted web click ID         |
| `data.visitor_session.fbclid`           | Facebook/Instagram click ID                    |
| `data.visitor_session.msclkid`          | Microsoft/Bing click ID                        |
| `data.visitor_session.ttclid`           | TikTok click ID                                |
| `data.visitor_session.li_fat_id`        | LinkedIn click ID                              |
| `data.visitor_session.ga_client_id`     | Google Analytics Client ID (from `_ga` cookie) |
| `data.visitor_session.ga_session_id`    | GA4 Session ID (from `_ga_XXXXXX` cookie)      |
| `data.visitor_session.utm_campaign`     | Campaign name from URL                         |
| `data.visitor_session.utm_term`         | Search term from URL                           |
| `data.visitor_session.utm_content`      | Ad variant/content from URL                    |
| `data.visitor_session.referrer_url`     | The referring page that brought the visitor    |
| `data.visitor_session.landing_page_url` | The first page the visitor landed on           |

If the caller could not be matched to a website visitor session (e.g., they dialed the number directly without visiting your site), `data.visitor_session` will be `null`.

***

### Timestamps & Time Zones

Every timestamp in a webhook payload is in **UTC** (Coordinated Universal Time), formatted as an [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) string ending in `+00:00` — for example, `2026-06-09T07:25:37+00:00`. The trailing `+00:00` is the time-zone offset, and it confirms the value is UTC.

{% hint style="warning" %}
**Webhook times are UTC; your dashboard shows local time.** Your call logs and analytics pages convert times into your campaign or workspace time zone so they're easy to read, but webhooks always send UTC. A time that looks an hour (or more) different from your dashboard is the **same moment shown in two time zones** — not a mismatch.
{% endhint %}

For example, a call that starts at `07:25 UTC` arrives in the webhook as `2026-06-09T07:25:37+00:00`. If that campaign uses UK time, the call's detail page shows it as **8:25 AM**, because the UK runs one hour ahead of UTC during British Summer Time (UTC+1). Both values are correct — they describe the same instant.

#### Timestamp fields

| Field                           | Where it appears                                                                   |
| ------------------------------- | ---------------------------------------------------------------------------------- |
| `created_at`                    | Top level — when the webhook event was generated                                   |
| `data.started_at`               | All call events — when the call started                                            |
| `data.qualified_at`             | `lead.qualified` — when the lead was qualified                                     |
| `data.summarized_at`            | `transcription.available` and `lead.qualified` — when the AI summary was generated |
| `data.voicemail.transcribed_at` | `voicemail.transcribed` — when the voicemail was transcribed                       |

{% hint style="success" %}
**Working with the times:** Because each timestamp carries the `+00:00` offset, most date libraries parse it correctly out of the box. Convert it to your preferred time zone for display, or store it as UTC and convert on read.
{% endhint %}

***

### Creating a Webhook Endpoint

<figure><img src="https://2905537093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXSbXRgC7knjpaMCHwuKc%2Fuploads%2Fgit-blob-e10921e24ece8ff406f1e889f2965a26026a9d00%2FXnapper-2025-12-01-23.14.16.png?alt=media" alt=""><figcaption><p>Create a webhook endpoint form</p></figcaption></figure>

1. Go to **Automations > Webhooks** in the sidebar
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**

{% hint style="warning" %}
**HTTPS Required:** Your endpoint URL must use HTTPS. HTTP URLs are not accepted for security reasons.
{% endhint %}

***

### 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)

```php
$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...
```

{% hint style="success" %}
**Pro Tip:** You can regenerate your signing secret anytime from the Edit page if you suspect it's been compromised.
{% endhint %}

***

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

{% hint style="info" %}
**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.
{% endhint %}

<figure><img src="https://2905537093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXSbXRgC7knjpaMCHwuKc%2Fuploads%2Fgit-blob-6982248ae42389cfbce8e2c60d06cc3a410d0040%2FXnapper-2025-12-01-23.15.59.png?alt=media" alt=""><figcaption><p>Test a webhook endpoint</p></figcaption></figure>

***

### Recording Links

Turn on **Recording links** to add a link to the call recording (or voicemail) to your webhooks. The link plays without a Ring Tonic login, so your CRM can save it on the contact and your team can listen from there.

{% hint style="warning" %}
**Anyone who has a link can play the recording until the link expires.** Every endpoint subscribed to the recording or voicemail events receives the links, including endpoints added through the API. Only workspace owners and admins can change this setting.
{% endhint %}

{% stepper %}
{% step %}

#### Open the Recording links card

Go to **Automations > Webhooks**. The **Recording links** card is below your endpoints.
{% endstep %}

{% step %}

#### Turn links on and choose how long they last

* Switch on **Include recording links in webhooks** (1)
* Under **Links expire after**, choose 1, 7, 14, 30, 60 or 90 days (2)
* Click **Save** (3)

<figure><img src="https://2905537093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXSbXRgC7knjpaMCHwuKc%2Fuploads%2Fgit-blob-fe0b7b4267eceba4c738da426eb981bc82449810%2Fwebhooks-recording-links-card.png?alt=media" alt="Recording links card with the switch on and Links expire after set to 30 days"><figcaption><p>Turn on recording links and choose how long each link works</p></figcaption></figure>
{% endstep %}

{% step %}

#### Check the new fields

Click **Send Test** on your endpoint and choose **Recording Available**. The test payload now carries the link fields, with a sample link.

<figure><img src="https://2905537093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXSbXRgC7knjpaMCHwuKc%2Fuploads%2Fgit-blob-9a4f30728f7db58ad5a650fd5a8e3fa45ca029f7%2Fwebhooks-recording-links-test-payload.png?alt=media" alt="Delivery details of a test recording.available webhook with the recording_download_url and recording_download_url_expires_at fields outlined"><figcaption><p>The recording link and its expiry in a test payload</p></figcaption></figure>
{% endstep %}
{% endstepper %}

| Event                                         | Link field                    | Expiry field                             |
| --------------------------------------------- | ----------------------------- | ---------------------------------------- |
| `recording.available`                         | `data.recording_download_url` | `data.recording_download_url_expires_at` |
| `voicemail.received`, `voicemail.transcribed` | `data.voicemail.download_url` | `data.voicemail.download_url_expires_at` |

While recording links are off, these fields are `null`. A new lifetime applies to links sent after you save it; links already sent keep their own expiry.

#### Revoking Links

Click **Revoke all links** and confirm to stop every link sent so far, including the ones saved in your CRM. New webhooks carry new links that work. Turning recording links off also stops every link already sent.

{% hint style="info" %}
Someone who opened a link shortly before you revoked it may still finish playing that recording.
{% endhint %}

***

### Payload Examples

All webhooks follow the same structure with event-specific data in the `data` object. The contact, form and text events (`form.submitted`, `contact.stage_changed`, `conversion.recorded`, `sms.received`) carry `event_id` (deduplicate on it), `workspace_id` and `occurred_at` around `data`.

<details>

<summary>form.submitted</summary>

Fires when a visitor submits a form on a campaign with Form Submissions on. `fields` holds the mapped and recognized fields (name, email, phone, company, custom fields); `detected_fields` lists every other field [Auto-detect](https://help.ringtonic.app/guides/form-submissions.md#auto-detect-fields) captured, with the label the visitor saw. It is an empty list when Auto-detect is off or found nothing.

```json
{
  "event": "form.submitted",
  "event_id": "evt_01JCZ8Q7M5W9V3T2K4R6N8P0AB",
  "workspace_id": 1,
  "occurred_at": "2026-11-06T18:42:10+00:00",
  "data": {
    "form_submission_id": 27,
    "campaign_uuid": "a309dbca-4417-469f-afa6-c0a8c1197db3",
    "contact_id": 177,
    "fields": {
      "name": "Priya Shah",
      "email": "priya@shahdesign.example",
      "phone": "+15035550147"
    },
    "marketing_params": {
      "utm_source": "google",
      "utm_medium": "organic"
    },
    "consent": null,
    "submitted_url": "https://harborpine.example/catering",
    "referrer_url": null,
    "origin": "https://harborpine.example",
    "submitted_at": "2026-11-06T18:42:10+00:00",
    "contact_uuid": "a31c2f4e-7b8d-4c1a-9e5f-2d6b8a0c4e71",
    "detected_fields": [
      { "name": "service", "label": "Service", "value": "Wholesale beans" },
      { "name": "monthly-volume", "label": "Monthly volume", "value": "20 lb" }
    ]
  }
}
```

</details>

<details>

<summary>sms.received</summary>

Fires when someone texts one of your tracking numbers.

* `body` is the text exactly as sent. It is empty for a text with only a picture.
* `media_count` is how many photos or files came with it. The files themselves are not included.
* `contact_uuid` is the existing contact with the sender's number, or `null`. A text never creates a contact.
* `campaign_uuid` is `null` when the number is not in a campaign.

```json
{
  "event": "sms.received",
  "event_id": "evt_01JD3K8W2N6Q4R7T9V1X3Z5B7C",
  "workspace_id": 1,
  "occurred_at": "2026-11-21T17:05:12+00:00",
  "data": {
    "message_uuid": "a31f6c2e-9d4b-4e8a-b7c1-5f2e8d0a6b39",
    "from": "+15035550147",
    "to": "+15035550115",
    "body": "Hi! Do you have the Holiday Blend in whole bean? I'd like 2 bags at the Pearl cafe tomorrow.",
    "media_count": 0,
    "received_at": "2026-11-21T17:05:11Z",
    "tracking_number_uuid": "a31c09d7-2b6e-4f1a-8c3d-7e5b9a1f0c42",
    "tracking_number_name": "Facebook - Holiday Blend ad",
    "campaign_uuid": "a309dbca-4417-469f-afa6-c0a8c1197db3",
    "contact_uuid": "a31c2f4e-7b8d-4c1a-9e5f-2d6b8a0c4e71"
  }
}
```

</details>

<details>

<summary>call.blocked</summary>

Fires when a call from a blocked number is rejected. This event has a different payload structure than other call events since the call is never connected.

```json
{
  "event": "call.blocked",
  "created_at": "2026-01-15T14:30:00+00:00",
  "workspace": {
    "id": 1,
    "name": "My Workspace"
  },
  "data": {
    "blocked_number": "+15551234567",
    "called_number": "+15559876543",
    "caller_name": "John Spam",
    "caller_city": "San Francisco",
    "caller_state": "CA",
    "block_list_type": "workspace",
    "block_reason": "spam",
    "tracking_number": {
      "id": 1,
      "phone_number": "+15559876543",
      "friendly_name": "Sales Line"
    },
    "campaign": {
      "id": 1,
      "name": "Google Ads Campaign"
    }
  }
}
```

</details>

<details>

<summary>call.completed (base payload — shared by all call.* events)</summary>

This is the full base payload shared by `call.started`, `call.completed`, `call.missed`, `recording.available`, `transcription.available`, `lead.qualified`, `voicemail.received`, and `voicemail.transcribed`. Event-specific fields are appended on top (see the sections below).

```json
{
  "event": "call.completed",
  "created_at": "2026-01-15T14:30:00+00:00",
  "workspace": {
    "id": 1,
    "name": "My Workspace"
  },
  "data": {
    "call_log_id": 12345,
    "twilio_call_sid": "CA1234567890abcdef",
    "from_number": "+14155551234",
    "caller_name": "John Smith",
    "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",
    "visitor_session": {
      "gclid": "CjwKCAiA-sample-gclid-123",
      "gbraid": null,
      "wbraid": null,
      "fbclid": null,
      "msclkid": null,
      "ttclid": null,
      "li_fat_id": null,
      "ga_client_id": "1234567890.1234567890",
      "ga_session_id": "1234567890",
      "utm_campaign": "winter-sale-2026",
      "utm_term": "plumber near me",
      "utm_content": "ad-variant-a",
      "referrer_url": "https://www.google.com/search?q=plumber+near+me",
      "landing_page_url": "https://example.com/services/plumbing"
    },
    "started_at": "2026-01-15T14:27:35+00:00"
  }
}
```

</details>

<details>

<summary>recording.available</summary>

Includes all base fields plus:

```json
{
  "event": "recording.available",
  "data": {
    "recording_url": "https://ringtonic.app/call-logs/12345/recording",
    "recording_download_url": "https://ringtonic.app/api/v1/media/recordings/9d1c…?expires=1771079400&v=1&signature=…",
    "recording_download_url_expires_at": "2026-02-14T14:30:00Z",
    // ... all base call data
  }
}
```

`recording_url` opens only for someone signed in to Ring Tonic. `recording_download_url` plays without a login and is `null` unless [Recording Links](#recording-links) are on.

</details>

<details>

<summary>transcription.available</summary>

Includes all base fields plus:

```json
{
  "event": "transcription.available",
  "data": {
    "transcription": "Hi, I'm calling about your services...",
    "transcription_confidence": 0.95,
    "summary": "Customer called inquiring about services and pricing. Requested a callback.",
    "summarized_at": "2026-01-15T14:32:00+00:00"
    // ... all base call data
  }
}
```

</details>

<details>

<summary>lead.qualified</summary>

Includes all base fields plus:

```json
{
  "event": "lead.qualified",
  "data": {
    "lead_status": "qualified",
    "qualification_reason": "Customer interested in premium package",
    "qualification_confidence": 0.89,
    "deal_value": 2500.00,
    "qualified_at": "2026-01-15T15:00:00+00:00",
    "tags": ["High Intent", "New Customer", "Service Inquiry"],
    "summary": "Customer called inquiring about services and pricing. Requested a callback.",
    "summarized_at": "2026-01-15T14:32:00+00:00"
    // ... all base call data
  }
}
```

</details>

<details>

<summary>voicemail.received</summary>

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

```json
{
  "event": "voicemail.received",
  "data": {
    "voicemail": {
      "recording_url": "https://ringtonic.app/call-logs/12345/voicemail-recording",
      "duration": 15,
      "download_url": "https://ringtonic.app/api/v1/media/voicemails/9d1c…?expires=1771079400&v=1&signature=…",
      "download_url_expires_at": "2026-02-14T14:30:00Z"
    },
    // ... all base call data
  }
}
```

</details>

<details>

<summary>voicemail.transcribed</summary>

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

```json
{
  "event": "voicemail.transcribed",
  "data": {
    "voicemail": {
      "recording_url": "https://ringtonic.app/call-logs/12345/voicemail-recording",
      "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",
      "download_url": "https://ringtonic.app/api/v1/media/voicemails/9d1c…?expires=1771079400&v=1&signature=…",
      "download_url_expires_at": "2026-02-14T14:30:00Z"
    },
    // ... all base call data
  }
}
```

</details>

***

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

{% hint style="danger" %}
**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.
{% endhint %}

#### Manual Retry

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

<figure><img src="https://2905537093-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FXSbXRgC7knjpaMCHwuKc%2Fuploads%2Fgit-blob-7e32b8521764f5aa85fa7990bbec4626c0d5b686%2FXnapper-2025-12-01-23.19.06.png?alt=media" alt=""><figcaption><p>Manual retry a webhook delivery</p></figcaption></figure>

***

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

{% stepper %}
{% step %}
**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**

{% hint style="success" %}
For more details, see [GHL's Inbound Webhook documentation](https://help.gohighlevel.com/support/solutions/articles/155000003147-workflow-trigger-inbound-webhook).
{% endhint %}
{% endstep %}

{% step %}
**Create the Ring Tonic Endpoint**

* In Ring Tonic, go to **Automations > Webhooks** → **Add Endpoint**
* Enter a name: `GoHighLevel Integration`
* Paste the GHL Webhook URL from Step 1
* Select events: `call.completed`, `call.missed`, and `recording.available` if you want the call recording in GHL
* Click **Create Endpoint**
  {% endstep %}

{% step %}
**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
  {% endstep %}

{% step %}
**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."
    {% endstep %}

{% step %}
**Save the Call Recording on the Contact (optional)**

The recording link arrives in its own `recording.available` webhook, shortly after the call ends.

1. In Ring Tonic, turn on [Recording Links](#recording-links) and choose how long links last.
2. In GHL, create a custom contact field, for example **Call Recording**.
3. Send a **Recording Available** test from Ring Tonic so GHL receives a sample with the link field.
4. In the workflow, add an **If/Else** on `{{event}}` equals `recording.available`. In that branch, add **Create/Update Contact** with:
   * Phone: `{{data.from_number}}`
   * Call Recording: `{{data.recording_download_url}}`

Your team can now open the recording from the contact without a Ring Tonic login.

{% hint style="info" %}
A link stops working when it expires. Choose a lifetime that covers how long your team needs to listen from GHL.
{% endhint %}
{% endstep %}
{% endstepper %}

#### 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_download_url`           | Custom Field (recording link, no login needed; see [Recording Links](#recording-links)) |
| `data.visitor_session.gclid`            | Custom Field (Google Ads click ID for offline conversion upload)                        |
| `data.visitor_session.fbclid`           | Custom Field (Facebook click ID for CAPI conversions)                                   |
| `data.visitor_session.ga_client_id`     | Custom Field (stitch the call to a GA4 session)                                         |
| `data.visitor_session.utm_campaign`     | Custom Field (campaign name)                                                            |
| `data.visitor_session.landing_page_url` | Custom Field (entry page)                                                               |

{% hint style="success" %}
**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.
{% endhint %}

***

### Common Questions

<details>

<summary>Why do webhook times differ from the times in my dashboard?</summary>

Webhook timestamps are always in **UTC** — you'll see `+00:00` at the end of each time. Your dashboard, call logs, and analytics convert times into your campaign or workspace time zone so they're easier to read.

So a call delivered as `07:25 UTC` in the webhook can appear as `08:25` on the call detail page if the campaign is on a time zone that's an hour ahead — for example, UK time during British Summer Time.

It's the same moment shown two ways, so nothing is wrong. See the **Timestamps & Time Zones** section above for the full list of timestamp fields and how to convert them.

</details>

<details>

<summary>What HTTP method is used?</summary>

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

</details>

<details>

<summary>How many times will you retry a failed delivery?</summary>

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.

</details>

<details>

<summary>How quickly are webhooks sent?</summary>

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

</details>

<details>

<summary>What response should my server return?</summary>

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

</details>

<details>

<summary>How long do you store delivery logs?</summary>

Delivery logs are retained for 30 days.

</details>

<details>

<summary>Can I have multiple endpoints for the same event?</summary>

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

</details>
