Получение кодов из SMS и голосовых звонков через вебхук: руководство по API

Вебхук отправляет на ваш сервер каждое SMS и каждый звонок на вашем номере. Короткий звонок приходит с текстом и продиктованным в нём кодом.

Вебхук отправляет на ваш сервер каждое 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 продолжают приходить. Подробнее: тарифы.

Что дальше