Real-Time Event Webhooks Setup | Ringg AI Developers

Webhooks let your backend receive call events without polling Ringg APIs. Configure subscriptions on an assistant, then Ringg sends HTTP requests to your endpoint whenever selected events occur.

Event types

Event type	Trigger	Typical use
`call_started`	A call is initiated	Mark a call as queued or started in your system
`call_completed`	A call attempt finishes	Update status, duration, transcript, and retry data
`recording_completed`	Recording is processed	Store or display recording URL
`platform_analysis_completed`	Ringg analysis completes	Store summary, classification, and key points
`client_analysis_completed`	Custom analysis completes	Store your configured custom analysis result
`all_processing_completed`	All post-call processing is done	Receive the final consolidated call payload

For most production integrations, start with all_processing_completed. Add earlier events only when your product needs live progress updates.

Configure subscriptions

Use PATCH /agent/v1 with operation: "edit_event_subscriptions". Authenticate the Ringg API request with X-API-KEY.

curl --request PATCH "https://prod-api.ringg.ai/ca/api/v0/agent/v1" \
  --header "X-API-KEY: $RINGG_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "operation": "edit_event_subscriptions",
    "agent_id": "your-agent-id",
    "event_subscriptions": [
      {
        "event_type": ["all_processing_completed"],
        "callback_url": "https://api.example.com/webhooks/ringg",
        "headers": {
          "Authorization": "Bearer your-webhook-receiver-token",
          "Content-Type": "application/json"
        },
        "method_type": "POST"
      }
    ]
  }'

The headers object is not used to authenticate your call to Ringg. Ringg sends those headers to your webhook endpoint when delivering events. If your UI needs live progress, subscribe to earlier events in addition to the final event.

{
  "operation": "edit_event_subscriptions",
  "agent_id": "your-agent-id",
  "event_subscriptions": [
    {
      "event_type": ["call_started", "call_completed", "all_processing_completed"],
      "callback_url": "https://api.example.com/webhooks/ringg",
      "headers": {
        "Authorization": "Bearer your-webhook-receiver-token",
        "Content-Type": "application/json"
      },
      "method_type": "POST"
    }
  ]
}

Endpoint requirements

Your webhook receiver should:

Use HTTPS.
Accept the method you configured, usually POST.
Return a 2xx response quickly after validating and storing the event.
Do heavy processing asynchronously in your own queue.
Handle duplicate events idempotently.
Store call_id, event_type, and received timestamp for debugging.

Idempotency key

Use call_id plus event_type as your primary dedupe key. If your workflow can receive multiple attempts for the same event, update the existing record instead of creating duplicates.

app.post("/webhooks/ringg", async (req, res) => {
  const event = req.body;
  const dedupeKey = `${event.call_id}:${event.event_type}`;

  await saveWebhookEventOnce(dedupeKey, event);

  res.status(204).send();
});

Authentication patterns

Secure your endpoint with a token that you control. Put that token in the subscription headers. Common patterns:

Authorization: Bearer your-webhook-receiver-token
X-Webhook-Secret: your-shared-secret
Provider-specific gateway authentication in front of your API

Next steps

Webhook payloads

Review the JSON payloads Ringg sends for each event type.

Error handling

Learn retry behavior, timeouts, and response requirements.

Get Started

API Reference

Webhooks Setup

Telephony Integration

External Integrations

Initial Setup

Event types

Configure subscriptions

Endpoint requirements

Idempotency key

Authentication patterns

Next steps

Webhook payloads

Error handling

​Event types

​Configure subscriptions

​Subscribe to progress events

​Endpoint requirements

​Idempotency key

​Authentication patterns

​Next steps

Webhook payloads

Error handling

Event types

Configure subscriptions

Subscribe to progress events

Endpoint requirements

Idempotency key

Authentication patterns

Next steps