API Webhooks

The Ringover endpoint

Every integration gets its own webhook URL ending in an integration ID. You paste that URL into your Ringover settings once, and Ringover posts a JSON event to it after each call. The path is unique to your account and acts as the credential, so keep it private. The authentication page covers what that means in practice. A GET request to the same URL returns a small status payload, which is a quick way to confirm the integration still exists.

The checks that run before processing

Each incoming request passes through the same sequence.

• A rate limit of 120 requests per minute per integration. Anything above that gets a 429 with a Retry-After header, before any database work happens.
• An integration lookup. The integration has to exist, be a Ringover integration, and be active, otherwise the request is answered with a 404.
• A signature check, when a webhook secret is stored. The HMAC is verified against the raw body and a mismatch is rejected with a 401. Ringover does not sign its webhooks, so for Ringover integrations this step is skipped and the request is logged with the calling IP address instead.
• Payload validation. The body is parsed and checked against a schema. Malformed JSON or an unexpected shape is answered with a 400 and nothing is written.

What happens to a call

Once the payload is accepted, Coldread decides whether the call is worth processing. Calls that do not meet the criteria are acknowledged and skipped. For the rest, the contact is looked up by normalised phone number and created if it is new, then the call record is written. Calls are matched on the provider call ID within your organisation, so a repeat delivery updates the existing record rather than creating a duplicate.

Coldread then resolves which member of your team made or took the call, using the agent email, the agent name and the phone numbers on the event. If there is a recording, the call is queued for transcription and analysis in the background. Calls shorter than your minimum transcription duration, ten seconds unless you change it, are marked complete and skipped without being transcribed. The endpoint returns its 200 quickly and the slow work happens afterwards, which is what keeps Ringover from retrying.

Relaying payloads to your own URL

If you set a relay URL on the integration, Coldread forwards the original Ringover payload to it. This is useful when the same call events already drive an automation of your own and you do not want to choose between the two. The auth token is stripped from the payload before it is stored or forwarded.

Relays are durable rather than fire and forget. Each one is recorded in the database, sent with an idempotency key header so your receiver can deduplicate, and retried with exponential backoff if it fails. A relay that never succeeds ends up in a dead letter queue you can inspect, and a scheduled sweep picks up anything that got stuck. Skipped calls are relayed too, so your system receives everything Ringover sent.

Not yet available

• Subscribing to Coldread events such as transcript ready or analysis complete
• Choosing which event types you receive, or filtering them
• Aircall webhooks. Aircall support is coming soon and is waitlist only
• Signed outbound payloads, beyond the idempotency key on relays