先验证
每个事件都带有两个标头:X-Meteor-Timestamp 和 X-Meteor-Signature;签名标头的格式为 t=…,v1=…,需要比较的十六进制摘要是 v1= 之后的部分。签名是以端点密钥为键,对时间戳、一个点号和原始请求正文计算出的 HMAC-SHA256。重新计算签名,以恒定时间比较,并拒绝超过五分钟的时间戳,使截获的请求无法在之后被重放。这一步必须在解析之前完成:经过解析再重新序列化的正文不会匹配,即使看起来完全相同。在 Flask 中,原始正文是 request.get_data(),在 Django 中是 request.body;在 Express 中,请为 Webhook 路由挂载原始正文解析器。
import hashlib, hmac, os, time
# 以逗号分隔,这样轮换期间可以同时保留两个密钥。
SECRETS = [s.encode() for s in os.environ["WEBHOOK_SECRETS"].split(",")]
def verify(raw_body, timestamp, signature):
# X-Meteor-Timestamp 为 Unix 秒数;X-Meteor-Signature 为 "t=...,v1=<十六进制摘要>"。
try:
ts = int(timestamp)
except (TypeError, ValueError):
return False
if abs(time.time() - ts) > 300: # 五分钟
return False
given = (signature or "").split("v1=")[-1].encode()
signed = timestamp.encode() + b"." + raw_body
for secret in SECRETS:
expected = hmac.new(secret, signed, hashlib.sha256).hexdigest()
if hmac.compare_digest(expected.encode(), given):
return True
return FalseNode 中的同样检查:
const crypto = require("crypto");
function verify(rawBody, timestamp, signature, secrets) {
const ts = Number(timestamp);
if (Number.isNaN(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false;
const given = Buffer.from(String(signature || "").split("v1=").pop());
return secrets.some((secret) => {
const expected = Buffer.from(crypto.createHmac("sha256", secret)
.update(timestamp + ".").update(rawBody).digest("hex"));
return expected.length === given.length && crypto.timingSafeEqual(expected, given);
});
}验证失败时返回 401 并记录原因,但绝不记录密钥。标头格式以 Webhook 文档为准,HMAC 签名词条解释了其原理。
快速确认
你有 5 秒时间返回任意 2xx。不要在请求中执行实际工作:验证,把事件写入队列或数据表,然后返回 200。内联更新三个系统的处理程序,会在其中一个系统变慢的那天超时,而每次超时都会变成一次重试,且可能在第一次尝试仍在运行时到达。
算一算就清楚了。假设一个 100,000 条消息的群发任务,每条消息最多产生两个事件,先是已发送,然后是已送达或失败:共 200,000 个请求。分散在一小时内,平均约为每秒 56 个(200,000 ÷ 3,600),峰值还会更高。每个请求花 300 毫秒做内联工作的处理程序,仅为跟上平均速度就需要约 17 个并发请求(56 × 0.3);只存一行、20 毫秒内就返回的处理程序,大约只需要一个。
@app.post("/hooks/sms")
def sms_hook():
raw = request.get_data() # 原始字节,未经任何解析
if not verify(raw, request.headers.get("X-Meteor-Timestamp", ""),
request.headers.get("X-Meteor-Signature", "")):
return "", 401
inbox_insert(raw) # 持久化写入;忽略重复项
return "", 200 # 其余工作都在工作进程中完成只有在事件存储完成后才返回 2xx。如果数据库宕机,请返回 5xx,让重试计划把事件送回来,而不是确认一个你已经丢失的事件。
去重
重试一定会发生,而每次尝试都带有相同的事件 ID。用唯一索引保存已处理的 ID,并把重复事件视为成功。这就是幂等处理的全部内容,只需一张表:
CREATE TABLE webhook_inbox (
event_id text PRIMARY KEY,
payload jsonb NOT NULL,
received_at timestamptz NOT NULL DEFAULT now(),
processed_at timestamptz
);
INSERT INTO webhook_inbox (event_id, payload)
VALUES (:event_id, :payload)
ON CONFLICT (event_id) DO NOTHING;工作进程读取 processed_at 为空的行,在一个事务中应用这些行并设置该字段。从控制面板重放的事件同样保留原始事件 ID,因此即使其中部分事件此前已经到达,批量重放也是安全的。同样的思路也能保护你的出站调用;参见幂等密钥。
按状态而非到达顺序排序
送达顺序不受保证,而重放的事件本来就会在数天后到达。如果你只保存最后收到的事件,迟到的已发送就会撤销已送达。为每个状态设定等级,并且只允许向前推进:
| 状态 | 等级 | 可被以下状态取代 |
|---|---|---|
| 排队中(queued) | 0 | 已发送、已送达、失败 |
| 已发送(sent) | 1 | 已送达、失败 |
| 已送达(delivered)、失败(failed) | 2 | 无:两者均为最终状态 |
UPDATE messages
SET status = :status, status_rank = :rank
WHERE id = :message_id AND status_rank < :rank;不要按 X-Meteor-Timestamp 标头排序:重放的事件会带上新的时间戳和签名,但保留原始事件 ID,因此该标头表示的是事件签名的时间,而不是消息状态变化的时间。在只返回运营商确认的目的地,已发送就是最终的成功状态,之后不会再有已送达;每个国家或地区页面都会说明预计返回哪种回执。
按类型路由事件
描述出站消息的事件有五种类型:message.sent、message.delivered、message.failed、message.expired 和 message.rejected;再加上活动事件和余额事件,共十种,每个端点只需订阅自己用到的事件。如果你租用了支持入站的号码,回复也会以事件形式到达。请在工作进程中而不是在请求处理程序中按类型分派,并对尚未处理的类型同样返回 2xx,这样新类型会被存储并忽略,而不会被重试六次。
原始消息上的两个字段让路由变得简单。reference 最多 128 个字符,由你自行定义,会在 Webhook 中原样返回,因此事件无需查找表就能找到对应的订单、预约或验证记录。webhook_url 可为单条消息覆盖端点,仅限 HTTPS,这样验证码流量可以直接报告给认证服务,而群发流量则发往分析系统。message.failed 事件附带易懂的原因和原始运营商代码;SMS 为何失败说明了每种原因应如何处理。
重试、故障与重放
每个事件在 24 小时内有 6 次尝试:立即一次,然后分别在 +1 分钟、+5 分钟、+30 分钟、+2 小时和 +12 小时。最后一次尝试之后,事件会被标记为未送达。5 秒内未返回 2xx 的任何响应都算一次失败的尝试,包括 401 和 404;因此,部署时被移动的路由,或者只在一处更改的密钥,看起来与故障完全一样。
- 一次部署或短暂波动不会造成任何损失:后续尝试会在你恢复后到达。
- 持续数小时的故障只会延迟事件而不会丢失事件,前提是后续尝试落在你恢复之后。
- 一天或更长时间的故障,或者错误的密钥对所有请求都返回 401,会耗尽全部六次尝试,这些事件将作为未送达事件在控制面板中等待处理。
先修复端点,用一次单独的重放确认,然后批量重放其余事件。重放的事件保留原始事件 ID,并带有新的时间戳和签名,因此能通过五分钟检查;去重会吸收你已经收到的事件,状态等级则负责处理顺序。未送达列表会将事件保留 30 天;更多内容见从控制面板重放。
两端都要监控
在你这一端,针对以下情况设置告警:
- 你的 5xx 比例,以及 401 比例:部署后 401 突然增加,通常是密钥或正文解析的问题,而不是攻击;
- 处理延迟超过两秒,远在 5 秒限制之内;
- inbox 表的积压量,以及其中最早一条未处理行的等待时长,它们能发现端点指标永远看不到的工作进程停滞。
在控制面板中,每个端点都会显示成功率、最近一次失败和平均响应时间,未送达列表则给出每个事件最近的状态码或错误。请结合起来解读:成功率下降而平均响应很快,通常意味着端点在快速返回错误的状态码。
轮换密钥
当知道密钥的人离开、密钥可能已经泄露时,都应轮换密钥,平时也要按固定计划轮换。从控制面板轮换后,新旧两个密钥在 24 小时内同时有效,因此接受密钥列表的验证程序在切换期间能持续工作:
- 在控制面板中轮换,并复制新密钥。
- 将它与旧密钥一起加入验证程序的列表,然后部署。
- 记录匹配的是哪个密钥;一旦事件能用新密钥通过验证,就移除旧密钥,并且要远早于 24 小时期满。
把密钥保存在密钥管理服务或环境变量中,绝不要放进代码仓库或日志。
上线前测试
使用 sk_test_ 密钥发送的消息会像正式消息一样经过验证和计价;不会发送或计费,但 Webhook 仍会触发,并像正式事件一样签名。因此整条路径都可以免费测试;参见测试密钥。在第一次正式群发之前,请确认:
- 真实事件能被存储,并在一秒内得到响应;
- 改动一个字节的同一正文会得到 401;
- 十分钟前的时间戳会得到 401;
- 同一事件送达两次只产生一行;
- 已送达之后迟到的已发送,不会改变已送达状态;
- 数据库停止时,处理程序会迅速返回 5xx,而不是挂起。
有内容不清楚或已经过时?请在支持页面告诉我们;修正内容会更新到指南中,同时更新修订日期。
