通过 Webhook 接收短信和语音通话验证码:API 指南

Webhook 会在您号码上的每条短信和每通电话到达时,把它推送到您的服务器;自 2026 年 11 月起,短通话会附带转写文本和其中读出的验证码,因此语音验证码也能以文本形式交给您的程序。

本指南会搭建接收端,校验每个请求确实来自我们,并处理这两类验证码。指南假设您已经有 API 密钥和号码;如果还没有,请先阅读用 API 自动完成短信验证。

为什么有些验证码通过电话送达

许多服务在短信收不到时会提供“改为电话告知”,也有一些服务只发送语音验证码。电话里由机器人读出数字。使用 SMS Activate App 的私人号码时,这通电话会像短信一样到达您的号码。

每通时长不超过一分钟的录音通话,在到达时都会转成文本。您会得到:

  • transcript:通话内容,或 null。
  • code:通话中读出的验证码(4 到 8 位数字),或 null。
  • transcriptStatus:done、empty(没有语音)、failed、toolong(超过一分钟)、overbudget 或 off。

录音链接的有效期为 24 小时。文本会一直保留。

第 1 步:把号码指向您的服务器

为单个号码设置 webhook:

该地址必须使用 HTTPS,并且在保存之前以 2xx 状态码响应我们的检查。若要一次接收您所有号码的事件,请改为通过 PATCH /v1/me 在账户上设置 webhookUrl。

第 2 步:获取签名密钥

返回结果是 {"secret": "whsec_..."},只显示一次。请把它和您的 API 密钥保存在一起。每次调用都会签发新密钥,旧密钥在下一次投递时失效,因此请只在能同时更新服务器的时候轮换密钥。

第 3 步:校验每个请求

每个请求都带有三个请求头:

  • x-vpn-event:sms.received、call.received、recording.ready 等。
  • x-vpn-timestamp:签名时间,单位为 Unix 秒。
  • x-vpn-signature:v1= 加上十六进制的 HMAC-SHA256。

签名是用您的密钥对 v1.<timestamp>.<raw body> 计算的 HMAC-SHA256。请在任何 JSON 解析之前,基于原始字节计算签名,并拒绝与您服务器时钟相差超过五分钟的时间戳。

在 Node.js 中使用 Express:

请先尽快返回 2xx,再处理耗时的工作。

第 4 步:从两类事件中提取验证码

短信(sms.received):

通话录音(recording.ready,在通话结束几秒后发送):

一个处理函数即可同时处理两者:

请优先使用 code 字段,而不是自己解析 transcript:机器人常常重复数字,或者逐位读出,而 code 已经把它们合成一个字符串。

第 5 步:接入真实流量前先测试

  • POST /v1/me/webhook-test 会向您的接收端发送一个 webhook.test 事件。
  • GET /v1/me/webhook-deliveries 会列出最近的投递记录:事件、是否投递成功、您服务器返回的状态码以及尝试次数。

如果投递失败,请先查看这里:常见原因是密钥错误、在校验之前就解析了请求体,或者响应太慢。

没有 webhook?通过 API 读取通话

如果没有服务器,可以在需要时读取某个号码的通话:

每通电话都带有同样的 transcript、code 和 transcriptStatus。在网站的账户中,验证码显示在通话下方,轻点一下即可复制。

通话和短信如何收费

号码上的呼入通话(按分钟计)和短信按各国家的价格从您的余额中扣费,价格以 usagePricing(callCents、smsCents、advanceUsd)的形式返回在国家、搜索结果和您的号码中。余额为零时,号码仍可在一笔小额预支额度内继续使用;超出后,在您充值之前呼入通话会被拒绝,短信则照常接收。详见价格。

后续步骤