Authentication

Public API requests are authenticated with a Custom Integration API key (cik_live_…). The key identifies the integration and its workspace — there is no separate account or organization id to send.

Create a Custom Integration

Custom Integrations are available to organization admins and personal workspace owners.

Open Integrations

Open the Custom Integrations tab

Select the Custom Integrations tab, then click New custom integration. Give it a name that identifies the system you are connecting, such as Acme CRM.

Copy your credentials

Ringee shows two secrets when the integration is created:

the API key (cik_live_…) — used to authenticate your requests to Ringee;
the webhook signing secret (whsec_…) — used to verify webhooks Ringee sends to you.

Copy both immediately and store them in your server-side secret manager.

Set your webhook URL

Under Settings, set the outbound URL to the public HTTPS endpoint that will receive Ringee events, and select which events you want to subscribe to.

Test the connection

Click Test webhook. Ringee sends a test.ping event to your endpoint and shows the HTTP status and latency it got back.

Authenticate a request

Send the API key in the X-Ringee-Api-Key header for inbound CRM events and click-to-call.

curl -X POST https://api.ringee.io/api/integrations/custom/webhook \
  -H "Content-Type: application/json" \
  -H "X-Ringee-Api-Key: cik_live_xxxxxxxx…" \
  -d '{
    "event": "contact.upserted",
    "eventId": "crm_9f1c2a7e",
    "occurredAt": "2026-05-23T14:30:00.000Z",
    "data": { "externalId": "ext_42", "phoneNumber": "+14155550123" }
  }'

AI Voice Agent endpoints accept either X-Ringee-Api-Key or Authorization: Bearer cik_live_…. Send exactly one authentication header; a request containing both is rejected with 401.

The API key is a server-side secret. Never send it from a browser, never commit it, never log it, and never store it in localStorage. If your CRM has a serverless layer (Supabase Edge Functions, Vercel functions, Lambda), all Ringee calls must happen there.

Key types

Ringee issues two different key types from the same integration. They are not interchangeable.

Key	Used by	Sent from	Safe in frontend?
`cik_live_…`	Inbound events, click-to-call and AI Voice Agents	Your server	No
`pk_live_…`	Dialer SDK	The browser	Yes
`whsec_…`	Webhook signature verification	Never sent	No

How keys are stored

The API key is stored hashed (SHA-256). Ringee can never show it to you again after creation — only its prefix, for example cik_live_a1b2c3d4.
The signing secret is stored encrypted at rest and decrypted only when signing an outbound delivery.

Rotating credentials

Rotate the API key

Click Regenerate API key in the integration settings. The previous key stops working immediately.

Rotating the API key also revokes every Dialer SDK publishable key (pk_live_…) minted for this integration. If you use both, mint a new publishable key right after rotating.

Rotate the signing secret

Click Regenerate signing secret. Ringee starts signing with the new secret on the next delivery and does not keep an overlap window. Store and deploy the returned secret immediately, then run Test webhook.

Disable an integration

Setting an integration’s status to disabled rejects its Public API key, stops outbound deliveries and invalidates its publishable keys. Queued deliveries are marked failed with integration disabled.

Workspace scope

An integration belongs to either a personal account or an organization. Everything it reads and writes is scoped to that workspace:

contacts and companies you upsert are created in that workspace;
only calls and activity from that workspace are sent to your webhook;
AI Voice Agent lists and call results are limited to that organization;
ownerEmail and agentEmail are resolved against that workspace’s members.

When an integration is organization-scoped, agentEmail is required for click-to-call — Ringee needs to know which member places the call.

AI Voice Agents require an organization-scoped integration. A key belonging to a personal workspace returns 403 for /api/v1/ai-voice-agents/*.

Manage the integration

Create integrations, change webhook subscriptions, rotate credentials and inspect delivery logs from Integrations → Custom Integrations in the Ringee dashboard. Those dashboard operations are not part of the Public API and do not accept a cik_live_… key.

Get Started

CRM to Ringee

Ringee to CRM

Guides

Create a Custom Integration

Authenticate a request

Key types

How keys are stored

Rotating credentials

Workspace scope

Manage the integration

Next steps

Send your first event

Verify webhooks

​Create a Custom Integration

​Authenticate a request

​Key types

​How keys are stored

​Rotating credentials

​Workspace scope

​Manage the integration

​Next steps

Send your first event

Verify webhooks

Create a Custom Integration

Authenticate a request

Key types

How keys are stored

Rotating credentials

Workspace scope

Manage the integration

Next steps