# Ringover Webhook API

**Canonical:** https://apis.io/apis/ringover/ringover-webhook-api/  
**Provider:** Ringover — https://apis.io/providers/ringover/  
**Base URL:** https://public-api.ringover.com/v2  
**Documentation:** https://developer.ringover.com/

Ringover Webhook API is one of 28 APIs that [Ringover](https://apis.io/providers/ringover/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. This API exposes 6 JSON Schema definitions. Tagged areas include webhook. The published artifact set on APIs.io includes an OpenAPI specification and 6 JSON Schemas.

Ringover uses webhooks to notify you any time that an event associated with your team occurs (ex: a new voicemail, the reception of a new message, a missed call...). A webhook is a URL that we call with a parameter that contains all the data about the event. It will allow you to create a **webhook handler** on your server in order to trigger specific actions in response to the event. You can configure your **webhooks** in the developer section of your Ringover dashboard. ## Securing your webhooks Every **call event** is signed with your **webhook key** (shown on the webhook configuration page of the Ringover dashboard, where you also configure your endpoint). Two signature versions exist; verify whichever your team is configured for. The raw webhook key is **never** sent as-is in a header — comparing a header to the key is not a valid check. ### V1 — current default (JWT, `Authorization` deprecated) The event is sent as a **JWT signed with `HS512`**, using your webhook key as the HMAC secret. The signed content is the concatenation of the **webhook URL** and the **JSON payload** (the request body). The same JWT is sent in two headers: - `X-Ringover-Webhook-Signature` — use this one. - `Authorization` — kept for backward compatibility only and **deprecated** (it will be removed; do not rely on it for new integrations). To verify, use any JWT library: `verify(token, <your webhook key>, { algorithms: ["HS512"] })`. The decoded JWT exposes the `url` (your configured endpoint) and `payload` (the event body: `resource`, `event`, `timestamp`, `data`, `attempt`) claims. ### V3 — recommended (HMAC-SHA256, fixed size) V3 is currently enabled **on request** and will become the default for newly activated webhooks. Unlike the V1 JWT (whose size grows with the payload — problematic for large events such as transcriptions), V3 keeps a fixed-size signature. The signature is `Base64( HMAC-SHA256( <your webhook key>, messageToSign ) )`, where `messageToSign` is the concatenation, **in this exact order**, of: 1. the HTTP method (`POST`) 2. the webhook URL 3. the JSON payload (the request body) 4. the timestamp Headers: - `X-Ringover-Webhook-Signature-V3` — the Base64 signature. - `X-Ringover-Request-Signature-V3-Timestamp` — the timestamp used to build `messageToSign`. Example: ``` HTTP method: POST Webhook URL: https://api.example.com/webhooks/call JSON payload: {"event":"ringing","resource":"call","timestamp":1554823493.762305,"data":{...}} Timestamp: 1554823493 messageToSign: POSThttps://api.example.com/webhooks/call{"event":"ringing","resource":"call","timestamp":1554823493.762305,"data":{...}}1554823493 ``` To verify, recompute `Base64(HMAC-SHA256(webhook key, messageToSign))` and compare it to `X-Ringover-Webhook-Signature-V3` (use a constant-time comparison). You can also reject requests whose `X-Ringover-Request-Signature-V3-Timestamp` is too old to mitigate replay attacks. > Warning: The `ivr_id` in the response body of webhook routes is offset by 10000 for legacy reasons (e.g. an ivr_id 22000 in the dashboard will be returned as 12000). ## Managing your webhooks from the API Webhooks can be configured from the developer section of the Ringover dashboard, or programmatically through the `/webhooks` endpoints. Both act on the same configuration — the one attached to the user who owns the API key you authenticate with. A webhook is a **subscription**: one `target_url` plus the set of `events` delivered to it. - The `uuid` of a webhook is **derived from its `target_url`** — an RFC 4122 **v5** UUID in the URL namespace. The same URL always yields the same id, that id never changes for the lifetime of the subscription, and you can compute it yourself instead of storing it: `uuidv5(target_url, URL namespace)`. - `target_url` is **immutable**. To deliver the same events to a different URL, create a new webhook and delete the old one. - Creating a webhook on a `target_url` that is already subscribed **merges** the event sets instead of creating a duplicate. - The same event can be delivered to **several** target URLs, except `contact.call` and `contact.search`: each of them accepts a **single** target URL. A request that would attach one of them to a second URL is rejected with `409` and nothing from that request is saved. Remove the event from the current URL first. - `signing_key` is the key used to sign the call, message and fax deliveries (see *Securing your webhooks* above). It is read-only and shared by every subscription of your configuration. - `contact.call` and `contact.search` each have their own key, returned in `event_signing_keys` on the webhook that holds the event. The key is generated on the first subscription and kept when the event is removed, so re-subscribing later reuses it. ### Event catalog These are the events you can subscribe to. The payload delivered to your `target_url` is described in the **Webhooks** section at the end of this page — the last column tells you which one to expect. | Event | Delivered when | Payload | |---|---|---| | `call.started` | An incoming call starts ringing | *Call ringing event* (`resource: call`, `event: ringing`) | | `call.answered` | A call is answered | *Call answered event* (`event: answered`) | | `call.ended` | A call is hung up | *Call hangup event* (`event: hangup`) | | `call.missed` | An incoming call is missed | *Call missed event* (`event: missed`) | | `call.voicemail` | A new voicemail is left | *Call voicemail event* (`event: voicemail`) | | `call.aftercall` | After-call data becomes available for a call | Several payloads with `resource: aftercall`. See *After-call events* below | | `sms.sent` | A message is sent | *Message event* (`resource: sms`, `event: sent`) | | `sms.received` | A message is received | *Message event* (`resource: sms`, `event: received`) | | `sms.delivery_receipt` | The carrier reports the delivery status of a sent message | *SMS delivery receipt event* (`resource: sms`, `event: sms.delivery_receipt`) | | `fax.received` | A fax is received | Not documented in this reference yet | | `contact.call` | A call starts, so you can return notes about the contact to the agent | *Contact event*. The `x-ringover-webhook-signature` JWT is signed with `event_signing_keys["contact.call"]` | | `contact.search` | A user searches contacts in the Ringover app, so you can return matching contacts from your API | *Contact Search event*. The `Authorization` header equals `event_signing_keys["contact.search"]` | ### After-call events Subscribing to `call.aftercall` delivers several requests for the same call, as each piece of data becomes available. Every payload has `resource: aftercall`. The `event` field says which piece just arrived. | `event` | Delivered when | Payload | |---|---|---| | `voicemail_available` | The voicemail audio file is ready | *Voicemail available event* | | `record_available` | The call recording is ready | *Record available event* | | `transcription_available` | The transcription is ready | *Transcription available event* | | `summary_available` | The Ringover summary is ready | *Summary available event* | | `empower` | Empower after-call data is ready | *Empower event* | | `comments_updated` | The call comment changes | *Comment updated event* | | `tags_updated` | The call tags change | *Tag updated event* | `call.voicemail` (`resource: call`, `event: voicemail`) reports that a voicemail was left. `voicemail_available` follows once the audio file is ready. Public CDN links in these payloads are deprecated. `record_link`, `voicemail_link`, and `transcription_link` are v1 URLs: anyone who has the link can download the file. Retrieve the file from the private field on the same event: - `record_available` — `private_record_link` - `voicemail_available` — `private_voicemail_link` - `transcription_available` — `private_transcription_link` To download a `private_*_link`, request that URL with your public API key in the `Authorization` header. Do not add a `Bearer` prefix: `Authorization: your-api-key-here`. For Ringover users, the summary is sent through `summary_available`. For Empower users, the summary, the transcription, and the follow-up actions are sent together through `empower`. **Permissions:** No specific permission required. A valid API key is sufficient, both to receive events and to manage subscriptions through the `/webhooks` endpoints. **Monitoring impact:** None. Your webhook configuration is resolved from the API key itself, so the Monitoring flag does not change what you can read or write.

## Operations (6)

| Method | Path | Summary |
|---|---|---|
| GET | `/webhooks` | List webhooks |
| POST | `/webhooks` | Create a webhook |
| GET | `/webhooks/{webhookId}` | Get a webhook |
| DELETE | `/webhooks/{webhookId}` | Delete a webhook |
| PUT | `/webhooks/{webhookId}/events` | Replace the events of a webhook |
| PATCH | `/webhooks/{webhookId}/events` | Add events to a webhook |

## Machine-readable artifacts (7)

- **OpenAPI** — https://artifacts.apis.io/ringover/openapi/ringover-webhook-api-openapi.yml
- **JSONSchema** — https://artifacts.apis.io/ringover/json-schema/ringover-calls-filter-schema.json
- **JSONSchema** — https://artifacts.apis.io/ringover/json-schema/ringover-empower-logs-calls-response-schema.json
- **JSONSchema** — https://artifacts.apis.io/ringover/json-schema/ringover-empower-logs-calls-request-schema.json
- **JSONSchema** — https://artifacts.apis.io/ringover/json-schema/ringover-call-empower-schema.json
- **JSONSchema** — https://artifacts.apis.io/ringover/json-schema/ringover-conversation-light-schema.json
- **JSONSchema** — https://artifacts.apis.io/ringover/json-schema/ringover-get-call-empower-res-body-schema.json

## Other Ringover APIs (12)

- [Ringover Blacklist API](https://apis.io/apis/ringover/ringover-blacklist-api/)
- [Ringover Callbacks API](https://apis.io/apis/ringover/ringover-callbacks-api/)
- [Ringover Calls API](https://apis.io/apis/ringover/ringover-calls-api/)
- [Ringover Campaigns API](https://apis.io/apis/ringover/ringover-campaigns-api/)
- [Ringover Cdn API](https://apis.io/apis/ringover/ringover-cdn-api/)
- [Ringover Channels API](https://apis.io/apis/ringover/ringover-channels-api/)
- [Ringover Conferences API](https://apis.io/apis/ringover/ringover-conferences-api/)
- [Ringover Contacts API](https://apis.io/apis/ringover/ringover-contacts-api/)
- [Ringover Conversations API](https://apis.io/apis/ringover/ringover-conversations-api/)
- [Ringover Empower API](https://apis.io/apis/ringover/ringover-empower-api/)
- [Ringover Groups API](https://apis.io/apis/ringover/ringover-groups-api/)
- [Ringover Ivrs API](https://apis.io/apis/ringover/ringover-ivrs-api/)

## Tags

webhook

---

Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/ringover/ringover-webhook-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/ringover/.