Вебхук отправляет на ваш сервер каждое SMS и каждый звонок на вашем номере, как только они поступают. С ноября 2026 года короткий звонок приходит вместе с текстом и продиктованным в нём кодом, поэтому код из звонка попадает в ваш обработчик в виде текста.
В руководстве вы настроите приёмник, проверите, что каждый запрос действительно пришёл от нас, и обработаете оба вида кодов. Предполагается, что у вас уже есть ключ API и номер. Если их нет, начните со статьи как автоматизировать SMS-верификацию через API.
Почему некоторые коды приходят звонком
Многие сервисы предлагают «позвонить вместо SMS», если сообщение не пришло, а некоторые отправляют только голосовые коды. Цифры зачитывает робот. Если у вас личный номер SMS Activate App, такой звонок поступает на ваш номер так же, как SMS.
Каждый записанный звонок длительностью до одной минуты расшифровывается в текст при поступлении. Вы получаете:
- transcript: что было сказано в звонке, или null.
- code: код подтверждения, продиктованный в звонке (от 4 до 8 цифр), или null.
- transcriptStatus: done, empty (речи нет), failed, toolong (длиннее одной минуты), overbudget или off.
Ссылка на запись действует 24 часа. Текст остаётся.
Шаг 1: направьте номер на ваш сервер
Задайте вебхук для одного номера:
Адрес должен работать по HTTPS и ответить на нашу проверку статусом 2xx, иначе он не сохранится. Чтобы получать события сразу по всем вашим номерам, задайте вместо этого webhookUrl для аккаунта через PATCH /v1/me.
Шаг 2: получите секрет для подписи
В ответе придёт {"secret": "whsec_..."}, он показывается один раз. Храните секрет рядом с ключом API. Каждый вызов выдаёт новый секрет, а старый перестаёт действовать со следующей доставки. Поэтому меняйте секрет, только когда можете одновременно обновить сервер.
Шаг 3: проверяйте каждый запрос
В каждом запросе три заголовка:
- x-vpn-event: sms.received, call.received, recording.ready и другие.
- x-vpn-timestamp: время подписи в секундах Unix.
- x-vpn-signature: v1= и HMAC-SHA256 в шестнадцатеричной записи (hex).
Подпись считается как HMAC-SHA256 с вашим секретом от строки v1.<timestamp>.<raw body>. Считайте её по необработанным байтам, до любого разбора JSON. Отклоняйте запрос, если метка времени отличается от показаний ваших часов больше чем на пять минут.
Пример на Node.js с Express:
Отвечайте быстро статусом 2xx, а долгую работу выполняйте после ответа.
Шаг 4: берите код из события любого типа
SMS (sms.received):
Запись звонка (recording.ready, через несколько секунд после окончания звонка):
Один обработчик покрывает оба случая:
Берите поле code, а не разбирайте расшифровку сами: робот часто повторяет цифры или читает их по одной, а code уже содержит их одной строкой.
Шаг 5: проверьте работу до реального трафика
- POST /v1/me/webhook-test отправляет на ваш приёмник событие webhook.test.
- GET /v1/me/webhook-deliveries показывает последние доставки: событие, доставлено ли оно, код ответа вашего сервера и число попыток.
Если доставка не удалась, смотрите сначала туда. Обычные причины: неверный секрет, тело запроса, разобранное до проверки подписи, или медленный ответ.
Нет вебхука? Читайте звонки через API
Если сервера нет, читайте звонки номера, когда они нужны:
У каждого звонка те же поля transcript, code и transcriptStatus. В личном кабинете на сайте код отображается под звонком и копируется одним касанием.
Сколько стоят звонки и SMS
Входящие звонки (поминутно) и SMS на номере оплачиваются с вашего баланса по цене для каждой страны. Цена возвращается в поле usagePricing (callCents, smsCents, advanceUsd) в списках стран, результатах поиска и ваших номерах. При пустом балансе номер продолжает работать в пределах небольшого аванса. Когда он исчерпан, входящие звонки отклоняются, пока вы не пополните баланс, а SMS продолжают приходить. Подробнее: тарифы.
Что дальше
- Поручите написать приёмник агенту для программирования: как использовать API SMS-верификации с Claude Code.
- Все маршруты и поля: документация API и файл OpenAPI.
- Что и когда изменилось: журнал изменений API.