Webhook 是网关在事件发生时(消息送达或失败、收到回复、余额过低)向你的端点发送的 HTTPS 请求,让你无需轮询状态。
轮询就是一遍又一遍地询问 API 是否有变化;大多数回答都是“还没有”,每次询问都要消耗一个计入速率限制的请求,而且变化发生后要过一阵才能得知。Webhook 把方向反了过来:你注册一个 HTTPS 端点,有事发生时,网关就向它 POST 一个事件。每个事件都带有 ID、类型、时间戳和数据,并且经过签名,以便你核实其来源。
投递语义是“至少一次”。当你的端点响应缓慢或宕机时,事件会被重试;而一次缓慢的成功之后若又发生重试,同一事件就可能到达两次;顺序同样无法保证。为生产环境打造的处理程序会把这些情况全部考虑在内:
- 基于原始正文验证签名,并拒绝过期的时间戳。
- 保存事件并立即返回 2xx;实际处理工作从队列中进行。
- 按事件 ID 去重。
- 状态变化只允许向前推进,使迟到的“sent”永远不会覆盖“delivered”。
示例
假设一次部署让某个端点下线了二十分钟。这段时间内产生的事件投递失败,随后按逐渐拉长的间隔重试,并在端点恢复后送达。处理程序逐一检查事件 ID,只应用之前没见过的事件,没有任何事件丢失。
常见错误
- 在响应之前执行耗时的工作,导致超时、重试和重复。
- 在验证签名之前就解析 JSON。
- 以为事件会按顺序到达,或只到达一次。
在 SMSMeteor:文档中列出的事件包括:消息流量方面的 message.sent、message.delivered、message.failed、message.expired 和 message.rejected;群发任务方面的 campaign.started、campaign.paused 和 campaign.completed;账户方面的 balance.low 和 balance.credited;每个端点可订阅其中任意子集。支持入站的租用号码收到的入站消息也通过 Webhook 送达。每个事件都在 X-Meteor-Signature 中带有 HMAC-SHA256 签名,并附有 X-Meteor-Timestamp。你的端点必须在 5 秒内返回 2xx,否则会重试投递,24 小时内共尝试六次(立即一次,然后分别在 +1 分钟、+5 分钟、+30 分钟、+2 小时和 +12 小时),之后事件会被标记为未送达。未送达的事件会在控制面板中按端点保留 30 天,可以逐个或批量重放,并保留原始事件 ID。测试密钥同样会触发 Webhook,签名方式与正式密钥相同。请参阅 Webhook 文档。
