Skip to main content

​
Overview

Ringg AI’s event-based webhook system allows you to subscribe to specific events for your AI agents and receive real-time callbacks when those events occur. This eliminates the need to continuously poll our API for updates.

​
Event Types

Our webhook system supports four main event types. You can subscribe to any or all of these events based on your needs:
Event TypeTriggerData Included
call_completedEvery call attempt finishesTranscript, duration, status, custom args
recording_completedRecording is processed and readyRecording URL and duration
platform_analysis_completedAI analysis completesKey points, summary, classification
client_analysis_completedCustom analysis completesResults based on your custom prompts

​
Configuration

To subscribe an agent to webhook events, use this PATCH request: 
curl --location --request PATCH 'https://prod-api.ringg.ai/ca/api/v0/agent/v1' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer your_token_here' \
--header 'X-API-KEY: your-api-key-here' \
--data '{
    "operation": "edit_event_subscriptions",
    "agent_id": "your-agent-id",
    "event_subscriptions": [
        {
            "event_type": "call_completed",
            "callback_url": "https://your-domain.com/webhooks/call-completed",
            "headers": {
                "Authorization": "Bearer your-webhook-token",
                "Content-Type": "application/json"
            },
            "method_type": "POST"
        },
        {
            "event_type": "recording_completed",
            "callback_url": "https://your-domain.com/webhooks/recording-completed",
            "headers": {
                "Authorization": "Bearer your-webhook-token",
                "Content-Type": "application/json"
            },
            "method_type": "POST"
        },
        {
            "event_type": "platform_analysis_completed",
            "callback_url": "https://your-domain.com/webhooks/platform-analysis",
            "headers": {
                "Authorization": "Bearer your-webhook-token",
                "Content-Type": "application/json"
            },
            "method_type": "POST"
        },
        {
            "event_type": "client_analysis_completed",
            "callback_url": "https://your-domain.com/webhooks/client-analysis",
            "headers": {
                "Authorization": "Bearer your-webhook-token",
                "Content-Type": "application/json"
            },
            "method_type": "POST"
        }
    ]
}'

​
Subscription Flexibility

You have complete flexibility in choosing which events to subscribe to:

​
Subscribe to Only Call Completion

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

​
Subscribe to Analysis Events Only

{
    "operation": "edit_event_subscriptions",
    "agent_id": "your-agent-id",
    "event_subscriptions": [
        {
            "event_type": "platform_analysis_completed",
            "callback_url": "https://your-domain.com/webhooks/analysis",
            "headers": {
                "Authorization": "Bearer your-webhook-token",
                "Content-Type": "application/json"
            },
            "method_type": "POST"
        },
        {
            "event_type": "client_analysis_completed",
            "callback_url": "https://your-domain.com/webhooks/custom",
            "headers": {
                "Authorization": "Bearer your-webhook-token",
                "Content-Type": "application/json"
            },
            "method_type": "POST"
        }
    ]
}

​
Requirements

​
Webhook Endpoint

Provide the full HTTPS URL where webhook notifications should be sent.

​
Authentication

Configure custom headers for secure webhook delivery. Common patterns:
  • Authorization: Bearer your-webhook-token
  • Custom API keys in headers
  • Additional security headers as needed

​
HTTP Methods

Supported methods:
  • POST (recommended)
  • PUT
  • PATCH

​
Response Requirements

Your endpoint must:
  • Return HTTP 200 status code to acknowledge receipt
  • Respond within 30 seconds to avoid timeout
  • Handle duplicate events using call_id for idempotency