RingCentral Webhook Setup

What You’re Setting Up

Webhook subscriptions that send real-time event notifications from RingCentral to our middleware. Instead of polling the API for new calls, RingCentral pushes events to us as they happen.

This is typically set up by us as part of the integration, but understanding it helps if you need to troubleshoot or manage the subscription.

Prerequisites

• A RingCentral developer account with an active app (set one up first)
• API credentials (Client ID, Client Secret, JWT)
• A publicly accessible webhook URL (we provide this)

Event Types We Subscribe To

For most CRM integrations, we subscribe to these event filters:

Telephony Session Events

/restapi/v1.0/account/~/telephony/sessions — real-time call state changes. We get notified when a call starts ringing, is answered, transferred, or disconnected. This is the primary event source for live call logging.

Call Log Events

/restapi/v1.0/account/~/extension/~/call-log — completed call records. These include duration, result (answered, missed, voicemail), and are the source of truth for historical call data.

Voicemail Events

/restapi/v1.0/account/~/extension/~/voicemail — new voicemail notifications. Useful when the integration needs to log missed calls with voicemail indicators or trigger follow-up tasks.

How Webhook Subscriptions Work

1. We Create the Subscription via API

We send a POST request to RingCentral’s subscription endpoint specifying:

• The event filters listed above
• Your webhook delivery URL (our endpoint)
• The delivery mode (WebHook)

2. RingCentral Validates the URL

RingCentral sends a validation request to the webhook URL. Our endpoint responds with the required validation token. If this fails, the subscription won’t activate.

3. Events Start Flowing

Once active, every matching event triggers an HTTP POST to our endpoint with the event payload in JSON format.

Subscription Renewal

This is the part that catches people off guard. RingCentral webhook subscriptions expire. The default expiration is typically around 15 minutes to 24 hours depending on configuration, but even longer-lived subscriptions need periodic renewal.

Our middleware handles this automatically by:

1. Tracking subscription expiration times
2. Renewing subscriptions before they expire
3. Re-creating subscriptions if renewal fails

If you notice events stop arriving, an expired subscription is the first thing to check.

Common Issues

Webhook URL Not Reachable

RingCentral must be able to reach the webhook URL over the public internet. Firewalls, VPNs, or private network configurations will block the validation request and prevent subscription creation.

Missed Events After Restart

If our middleware restarts or the subscription expires, there’s a gap where events are missed. We backfill these by polling the call log API for recent records after re-establishing the subscription.

Duplicate Events

RingCentral may deliver the same event more than once. Our middleware de-duplicates based on event IDs, but if you see duplicate CRM entries, this is the likely cause and we can investigate.

Subscription Limit

RingCentral limits the number of active subscriptions per app. If you hit this limit, older subscriptions need to be cleaned up before creating new ones.

Next Steps

• Set up call recording access: RingCentral Call Recording Access
• Learn about our VoIP CRM Integration services