Skip to main content
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 typeTriggerTypical use
call_startedA call is initiatedMark a call as queued or started in your system
call_completedA call attempt finishesUpdate status, duration, transcript, and retry data
recording_completedRecording is processedStore or display recording URL
platform_analysis_completedRingg analysis completesStore summary, classification, and key points
client_analysis_completedCustom analysis completesStore your configured custom analysis result
all_processing_completedAll post-call processing is doneReceive 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.

​
Subscribe to progress 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.