DEVELOPERS

Ringwise API

REST + JSON. Machine-readable spec: /api/v1/openapi.json

Authentication

Create a key in the portal under Developers (partners: ask your account manager). Send Authorization: Bearer rw_live_…. Keys are shown once and stored hashed. Limit: 120 requests/minute per key. Partner keys must pass ?client_id= for client data.

Endpoints

GET/api/v1/callsList calls (newest first, cursor pagination)
GET/api/v1/calls/{id}Call detail with transcript
GET/api/v1/appointmentsList appointments
GET/api/v1/messagesList messages taken by the agent
GET/api/v1/profileBusiness profile in use (read-only)
GET/api/v1/clientsPartner keys: attributed clients
GET/api/v1/webhooksList webhook endpoints
POST/api/v1/webhooksCreate a webhook endpoint (secret returned once)
DELETE/api/v1/webhooks/{id}Delete a webhook endpoint

Webhooks

call.completedappointment.bookedappointment.cancelledemergency.flagged

We POST { id, type, created, clientId, data } with headers Rw-Event and Rw-Signature. Respond with any 2xx within 8 seconds; failures are retried with backoff. Use id to de-duplicate. Endpoints must be public HTTPS.

// Node.js — verify the Rw-Signature header (t=<unix>,v1=<hex hmac-sha256 of "<t>.<raw body>">)
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(secret, rawBody, header, toleranceSec = 300) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? '');
  if (!m || Math.abs(Date.now() / 1000 - Number(m[1])) > toleranceSec) return false;
  const expected = createHmac('sha256', secret).update(m[1] + '.' + rawBody).digest();
  return timingSafeEqual(Buffer.from(m[2], 'hex'), expected);
}