Subscribe a Ringg AI agent to call, chat and analysis events from the dashboard: pick events, set the callback URL and headers, and know the per-event limits.
Event Subscription (webhooks) sends an HTTP request to your server when an agent’s conversation reaches a stage: a call starts or ends, its recording is ready, or its analysis finishes. Use it to update your CRM or trigger follow-ups without polling.In the dashboard: Agents (listed under Assistants in the sidebar) → open an agent → Advanced Settings → Event Subscription. On a multi-prompt agent, open Global Settings → Events subscription (see Global Settings).On a WhatsApp agent the list offers chat events instead of call events; see WhatsApp chat events.
Open Event Subscription. With no subscriptions yet, the New subscription form is already open; otherwise click Create Subscription (Add on a multi-prompt agent).
2
Set the method and URL
Pick a Method: GET, POST, PUT or PATCH (default POST). Enter the Callback URL, for example https://api.example.com/webhooks/ringg.
3
Select events
Under Select Events, tick one or more. Each is described in Events.
4
Add headers (optional)
Under Custom Headers, click Add Header and fill in a key and value, such as Authorization and Bearer <your-token>. Ringg sends these headers with every event, so your server can check them (see Authentication patterns).
A filled-in new subscription
5
Save
Click Create Subscription. It is enabled once the URL and at least one event are set. You see “Event subscription added” and a card with the Webhook URL, Events and Headers.
The card shows your URL and every event you ticked.
The list matches the agent’s channel. Voice and web agents get the call events, WhatsApp agents get Chat Completed, and every agent gets the analysis events. Hover the info icon next to an event for the same details as below.
Event
Fires
Carries
Call Started call_started
When an outbound call or web call begins. Not sent for inbound phone calls
Call ID, caller info, custom args, agent info
Call Ringing call_ringing
Dashboard test calls only, together with Call Started, once the carrier accepts the dial
”Subscription limit reached”. Create Subscription is hidden once every offered event has 4.
The same callback URL and event cannot appear twice
”Duplicate subscription”. Remove the duplicate, or add the event to the existing subscription.
A header with a key needs a value
”Add a value or remove this header”
The limit counts subscriptions per event, not in total. One URL subscribed to several events counts once against each of them. The API enforces the same rules with 400, and also rejects an event the agent’s channel can never produce.
After you save, Ringg masks the value of any header whose name contains authorization, api-key, token, bearer, secret, password, auth or key (so X-Idempotency-Key is masked too). A masked value shows its first 4 characters, for example sk_l***. In the dashboard a masked value is read-only:
To change it, click the pencil (Edit header value) and type the full new value. Leave it blank to keep the stored one.
If you change the Callback URL, or replace all of a subscription’s original events, masked values are cleared and you see “Header value cleared”: “The secret was tied to the previous target. Re-enter it before saving.”
Edit: open the card’s menu (⋮) and click Edit. The card turns into the form; change it and click Update Subscription. You see “Event subscription updated”.
Remove: open the menu and click Delete. It is removed at once, with no confirmation, and you see “Event subscription removed”.
On a multi-prompt agent the compact list has pencil and trash buttons instead of the menu. Changes there go into the agent’s draft; see Publish changes on a multi-prompt agent.
The server rejected the list. Check the URL, the 4-per-event limit and duplicate URL and event pairs, then save again.
My endpoint is not receiving events
Check the endpoint against the requirements and the error handling guide. Confirm the call reached the stage the event waits for: Recording Ready needs a recording, and the analysis events need a completed conversation.
