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)的形式返回在国家、搜索结果和您的号码中。余额为零时,号码仍可在一笔小额预支额度内继续使用;超出后,在您充值之前呼入通话会被拒绝,短信则照常接收。详见价格。
后续步骤
- 让编程智能体来编写接收端:在 Claude Code 中使用短信验证 API。
- 所有路由和字段:API 文档和 OpenAPI 文件。
- 更新内容与时间:API 更新日志。