Webhooks

Ringover calls a URL you configure in the Dashboard (Developer → Webhooks) whenever an event occurs. There is no POST /webhooks management API documented on the public site — configuration is dashboard-only.

Securing your webhooks (signature verification)

Every call event is signed with your webhook key (shown on the webhook configuration page of the Ringover Dashboard). 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 directly is not a valid check for these events.

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 same JWT is sent in two headers:

• X-Ringover-Webhook-Signature — use this one.
• Authorization — kept for backward compatibility only, deprecated, do not rely on it for new integrations.

Verify with any JWT library: verify(token, webhookKey, { algorithms: ["HS512"] }). The decoded JWT exposes url (your configured endpoint) and payload (the event body: resource, event, timestamp, data, attempt).

V3 — recommended (HMAC-SHA256, fixed size)

Enabled on request today; will become the default for newly activated webhooks. Unlike V1's JWT (which grows with payload size — an issue for large events like transcriptions), V3 keeps a fixed-size signature.

Signature: Base64( HMAC-SHA256(webhook_key, messageToSign) ), where messageToSign concatenates, in order, the HTTP method (POST), and other fields described in the dashboard's webhook configuration page.

Headers:

• X-Ringover-Webhook-Signature-V3 — the Base64 signature.
• X-Ringover-Request-Signature-V3-Timestamp — the timestamp used to build messageToSign.

Verify by recomputing the HMAC and comparing with a constant-time check. Optionally reject requests whose timestamp is too old (replay protection).

Per-event authentication (exceptions to V1/V3)

A few events use a different scheme instead of the general V1/V3 pair above:

All other events (call_ringing, call_answered, call_hangup, call_missed, call_voicemail, comment_updated, tag_updated, record_available, voicemail_available, transcription_available, summary_available, empower) follow the general V1/V3 scheme above.

Event catalog

The published docs list 17 webhook events under the webhook tag:

Verifying V1 (Node.js example)

const jwt = require('jsonwebtoken');

function verifyV1(token, webhookKey) {
  // decoded.payload = { resource, event, timestamp, data, attempt }
  // decoded.url = your configured endpoint
  return jwt.verify(token, webhookKey, { algorithms: ['HS512'] });
}

Verifying V3 (Node.js example)

const crypto = require('crypto');

function verifyV3(signatureB64, timestamp, method, path, body, webhookKey) {
  const messageToSign = `${method}${path}${timestamp}${body}`; // exact order per dashboard docs
  const expected = crypto
    .createHmac('sha256', webhookKey)
    .update(messageToSign)
    .digest('base64');

  return crypto.timingSafeEqual(
    Buffer.from(signatureB64),
    Buffer.from(expected),
  );
}

Confirm the exact byte layout of messageToSign on your webhook configuration page before shipping — the docs describe it as an ordered concatenation but the full field list is shown there per team.