Ringover

Ringover Webhook API

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, , { 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( , 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.

GitHub OpenAPI
Business capability
Webhook & Event Subscription Management BC-4270.80

Operations 6

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 #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/ringover/openapi/ringover-webhook-api-openapi.yml

Schemas & Data

📊
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

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/ringover:ringover-webhook-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

ringover-webhook-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  license:
    name: Proprietary – Contact us for usage terms
    url: https://www.ringover.com/contact
  description: '# Ringover Public API


    Welcome to the Ringover Public API. This RESTful API lets you integrate Ringover telephony, messaging, contacts, and AI analytics into your applications. ## Base URL


    | Region | Base URL |

    |--------|----------|

    | Europe | `https://public-api.ringover.com/v2` |

    | United States | `https://public-api-us.ringover.com/v2` |


    ## Authentication


    All requests must include your API key in the `Authorization` header:


    ```

    Authorization: your-api-key-here

    ```


    To create an API key:

    1. Open the Ringover Dashboard. 2. Navigate to **Developer > API Keys**. 3. Click **Create an API key**, select a user, and set a label. 4. Configure the permissions for this key (see Permissions below). ## Permissions


    Each API key is associated with **7 permission categories**, each configurable as **None**, **Read**, **Write**, or **Read+Write**:


    | Category | Controls access to |

    |----------|-------------------|

    | **Calls** | Call history, archives, live call controls, callbacks |

    | **Contacts** | Contact CRUD and phone number management |

    | **Users** | User listing, plannings, presences, groups, user blacklists |

    | **Numbers** | Phone number listing, team blacklist |

    | **IVRs** | IVR/scenario listing, tag management |

    | **Conversations** | SMS/Chat conversations, messages, SMS sending |

    | **Empower** | AI call analysis, summaries, moments, analytics |


    ### The Monitoring flag (Supervision)


    In addition to R/W permissions, each API key has a **Monitoring** toggle that controls the **scope** of data returned:


    | Monitoring | Effect |

    |------------|--------|

    | **OFF** | Your permissions give access to **your own data only** (your calls, your numbers, your conversations…) |

    | **ON** | Your permissions give access to **the entire team''s data** (all users, all calls, all conversations…) |


    Monitoring does **not** grant additional permissions — it widens the scope of existing ones. Some routes **require** Monitoring to be enabled and will return `401` without it. Conversely, some routes may ignore the Monitoring flag entirely or apply it differently — unless stated otherwise in the endpoint documentation, the default behavior described above applies. > Each endpoint in this documentation specifies its exact permission and monitoring requirements. ### Special cases


    - **Campaigns, Tasks, WhatsApp**: These routes do not require specific token permissions. A valid API key is sufficient. - **Empower**: Uses its own role system (Admin / Supervisor / User) in addition to the Empower R/W permission. - **Transcriptions**: Access is controlled by a team-level setting, not by the token permissions. - **Conferences**: All conference routes require Monitoring enabled. ## Rate Limiting


    A **2-request-per-second** rate limit is applied per API key. Exceeding this limit returns `429 Too Many Requests`. ## Pagination


    List endpoints support offset-based pagination with two parameters:

    - `limit_count`: Maximum number of items to return (default: 100, max varies by endpoint). - `limit_offset`: Number of items to skip (default: 0). Some call-related endpoints also support cursor-based pagination via `last_id_returned`. ## Error Responses


    | HTTP Code | Meaning |

    |-----------|---------|

    | `400` | Bad request — invalid parameters or body |

    | `401` | Unauthorized — invalid/expired API key, or access denied by permission/monitoring checks on most endpoints |

    | `403` | Forbidden — authenticated request refused by specific endpoint logic (notably some Empower routes) or upstream forwarded services |

    | `402` | Payment required — feature not available on your plan |

    | `404` | Resource not found |

    | `429` | Rate limit exceeded |

    | `500` | Internal server error |


    ## SCIM 2.0 Provisioning


    Ringover exposes a **SCIM 2.0** server (RFC 7643 / RFC 7644) for automated user and group provisioning from your identity provider (Okta, Microsoft Entra ID, …). It reuses the **same API key** as the REST API (`Authorization` header).'
  version: 2.1.0
  title: Ringover Public Webhook API
  x-logo:
    url: https://webcdn.ringover.com/app/img/misc/logo_app_redoc.png
    backgroundColor: '#FAFAFA'
    altText: Ringover Logo
  termsOfService: https://ringover.com/terms/
  contact:
    email: support@ringover.com
servers:
- url: https://public-api.ringover.com/v2
  description: Production server (Europe)
- url: https://public-api-us.ringover.com/v2
  description: Production server (United States)
security:
- Authorization: []
tags:


# --- truncated at 32 KB (83 KB total) ---
# Full source: https://artifacts.apis.io/ringover/openapi/ringover-webhook-api-openapi.yml