A webhook sends every SMS and call on your number to your server as it arrives, and since November 2026 a short call comes with its text and the code read out in it, so a voice code reaches your code as text.
This guide sets up the receiver, checks that each request really comes from us, and handles both kinds of code. It assumes you already have an API key and a number; if not, start with automate SMS verification with the API.
Why some codes come as a call
Many services offer "call me instead" when an SMS does not arrive, and some send only voice codes. A robot reads the digits out. With a private number from SMS Activate App, that call reaches your number like an SMS does.
Every recorded call of up to one minute is turned into text when it arrives. You get:
- transcript: what the call said, or null.
- code: the verification code read out in it (4 to 8 digits), or null.
- transcriptStatus: done, empty (no speech), failed, toolong (over one minute), overbudget or off.
The recording link works for 24 hours. The text stays.
Step 1: point the number at your server
Set the webhook for one number:
The address must be HTTPS and answer our check with a 2xx status before it is saved. To receive events for all your numbers at once, set webhookUrl on the account with PATCH /v1/me instead.
Step 2: get the signing secret
The answer is {"secret": "whsec_..."}, shown once. Store it next to your API key. Each call issues a new secret, and the old one stops at the next delivery, so rotate it only when you can update your server at the same time.
Step 3: verify every request
Each request carries three headers:
- x-vpn-event: sms.received, call.received, recording.ready, and others.
- x-vpn-timestamp: when it was signed, in Unix seconds.
- x-vpn-signature: v1= and an HMAC-SHA256 in hex.
The signature is HMAC-SHA256 with your secret over v1.<timestamp>.<raw body>. Compute it over the raw bytes, before any JSON parsing, and reject a timestamp more than five minutes from your clock.
In Node.js with Express:
Answer quickly with a 2xx and do slow work afterwards.
Step 4: take the code from either kind of event
An SMS (sms.received):
A call's recording (recording.ready, a few seconds after the call ends):
One handler covers both:
Prefer the code field over parsing the transcript yourself: the robot often repeats the digits or reads them one by one, and code already holds them as one string.
Step 5: test it before real traffic
- POST /v1/me/webhook-test sends a webhook.test event to your receiver.
- GET /v1/me/webhook-deliveries lists the last deliveries: the event, whether it was delivered, your server's status code and the number of tries.
If a delivery fails, look there first: a wrong secret, a body parsed before the check, or a slow answer are the usual causes.
No webhook? Read the calls by API
Without a server, read a number's calls when you need them:
Each call carries the same transcript, code and transcriptStatus. In the account on the website, the code shows under the call and copies in one tap.
What calls and SMS cost
Inbound calls (per minute) and SMS on a number are charged to your balance at a per-country price, returned as usagePricing (callCents, smsCents, advanceUsd) on countries, search results and your numbers. With an empty balance a number keeps working up to a small advance; past it, inbound calls are refused until you top up, and SMS keep arriving. See pricing.
Next steps
- Let a coding agent build the receiver: use the SMS verification API with Claude Code.
- Every route and field: API docs and the OpenAPI file.
- What changed and when: the API changelog.