> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ringg.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Initial Setup

> Configure webhook event subscriptions for assistants and receive real-time call, recording, and analysis events.

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         |

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

## Configure subscriptions

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

```bash theme={null}
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.

```json theme={null}
{
  "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.

```javascript theme={null}
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

<CardGroup cols={2}>
  <Card title="Webhook payloads" icon="braces" href="/webhooks/payloads">
    Review the JSON payloads Ringg sends for each event type.
  </Card>

  <Card title="Error handling" icon="circle-alert" href="/webhooks/error-handling">
    Learn retry behavior, timeouts, and response requirements.
  </Card>
</CardGroup>