Quickstart

In about 10 minutes you’ll add a lead with a test key, watch a pretend call play out, and receive its call.completed webhook, signed, on a page you can see in your browser.

Nothing here dials a real person or costs anything. A test key only ever sees sample data.

You need: a CallView login that can open Settings > API (an admin), a terminal with curl, and one campaign that is running.

1. Make a test key.

   In CallView, open Settings > API and click + Create API key. Under Test or Live, pick Test, and let it use all campaigns. Under What it can do, pick Full access if you’re the organization’s owner. Otherwise tick Read and Write for Leads and Webhooks, and Read for Campaigns, Calls and Events.

   Copy the key ID (ck_test_...) and the secret (cs_test_...). The secret is shown once, so put it somewhere safe now. Then, in your terminal:

   export CALLVIEW_KEY_ID=ck_test_paste_yours_here
   export CALLVIEW_SECRET=cs_test_paste_yours_here

2. Open a request bin.

   Go to webhook.site and copy Your unique URL. Any public HTTPS address that shows you what it receives will do.

3. Ask for call.completed events at that address.

   curl -X POST 'https://v2-api.callview.ai/api/v1/external/webhook_endpoints' \
     -u "$CALLVIEW_KEY_ID:$CALLVIEW_SECRET" \
     -H 'Content-Type: application/json' \
     -d '{ "url": "https://webhook.site/your-unique-id", "events": ["call.completed"] }'

   The reply has a secret that starts with whsec_. Copy it: it’s how you’ll check our signature in step 7, and you won’t see it again. Because you used a test key, this endpoint only ever gets test events.

4. Find a campaign.

   curl 'https://v2-api.callview.ai/api/v1/external/campaigns' \
     -u "$CALLVIEW_KEY_ID:$CALLVIEW_SECRET"

   Copy the id of a campaign that is running in CallView. A test key sees your real campaigns’ IDs and names, so the same campaign_id works later with a live key.

5. Add a lead with the magic number +15550100001.

   curl -X POST 'https://v2-api.callview.ai/api/v1/external/leads' \
     -u "$CALLVIEW_KEY_ID:$CALLVIEW_SECRET" \
     -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: quickstart-lead-1' \
     -d '{
       "campaign_id": "PASTE_THE_CAMPAIGN_ID",
       "external_id": "quickstart-1",
       "phone": "+15550100001",
       "name": "Test Lead",
       "call_now": true,
       "consent": { "source": "web_form", "agreed_at": "2026-10-06T16:58:02Z", "url": "https://example.com/quote" }
     }'

   You get 201 and "status": "queued". In test mode, +15550100001 plays a call where the lead is interested and someone on your team takes over. Test mode lists the other magic numbers.

   Note

   If the reply says "status": "held" with "held_reason": "campaign_paused", the campaign isn’t running. Pick one that is, or start it in CallView. A held lead waits, just as it would for real.

6. Watch the request bin.

   The pretend call starts a few seconds later and lasts about three and a half minutes, like a real one. Then call.completed arrives at your bin with "outcome": "interested" and "livemode": false. Names and notes are placeholders such as LEAD_NAME and AI_NOTE.

   You can also ask where the lead is at any time:

   curl 'https://v2-api.callview.ai/api/v1/external/leads?external_id=quickstart-1' \
     -u "$CALLVIEW_KEY_ID:$CALLVIEW_SECRET"

7. Check the signature.

   In the request bin, copy the raw body into a file called body.json, and copy the CallView-Signature header (it looks like t=1791306131,v1=5257a8...). Save one of these as a file, then run it with your whsec_ secret:

   Node

   node verify-signature.js whsec_your_secret 't=...,v1=...' body.json

   Python

   python verify_signature.py whsec_your_secret 't=...,v1=...' body.json

   PHP

   php verify-signature.php whsec_your_secret 't=...,v1=...' body.json

   The files are on Webhooks and signatures. It prints valid.

   Caution

   Do this within 5 minutes of the delivery. A signature older than that is refused on purpose, so nobody can replay an old event at you. Missed it? Send yourself a fresh one with Send a test event.

What next

• Wire your CRM to send leads as they arrive: Speed to lead.
• Handle every event, retries and repeats included: Webhooks and signatures.
• Try the other magic numbers (voicemail, no answer, a callback): Test mode.
• Ready for real calls? Make a live key, point a live webhook endpoint at your server, and change nothing else.

Prefer clicking to typing? Import the Postman collection. Its Quickstart folder runs steps 3 to 6 for you.