入站短信 Webhook：重试、事件顺序与接收幂等

出站短信占据仪表盘。入站才是 STOP、HELP 与客户回复真正落地之处——也是天真处理器制造重复工单、双重钱包副作用，以及「我们从未收到 STOP」合规幽灵的地方。若接收路径假设严格有序的恰好一次投递，第一次真实故障就会击垮你。

IOSOR 将入站消息放在与出站相同的白标预付费表面上：可核验的事件、品牌安全载荷，无需扎在外来运维门户里核对回复风暴。

为何 Webhook 会重试

Webhook 投递并非一次性承诺。当你的服务器未能及时响应（例如，返回 5xx 错误码，或在指定超时时间内无响应），或出现网络层面的不确定性错误时，平台会启动重试机制。这是一种至少一次投递（at-least-once delivery）的保障策略，旨在确保消息最终能送达。然而，重试本身引入了重复投递的可能性，这是设计幂等接收器的根本原因。

必须设计的三种失败模式

1. 重复投递：同一事件 ID 到达两次或以上。这可能导致重复的客户操作（例如，处理多个 STOP 命令）、重复的钱包扣款，或产生错误的合规警报。
2. 事件乱序：时间戳较晚的事件先于时间戳较早的事件到达。这可能导致状态回滚（例如，“已送达”状态被更早的“已发送”状态覆盖），或者更危险地，一个“STOP”命令可能在“START”确认后才到达，导致被忽略，从而产生持续的违规发送。
3. 部分/模糊失败：你的服务器成功处理了事件，但确认（ACK）未能送达平台。这可能导致平台因未收到确认而触发重试，最终造成重复处理。

幂等：同时修好三种失败的一个属性

实现幂等性是应对上述三种失败模式的关键。核心在于：

1. 提取平台事件/消息 ID：使用平台提供的、不可变的唯一事件标识符，绝不基于时间戳或内容自行生成。
2. 数据库唯一约束：将此平台 ID 设为数据库表的主键或唯一索引，确保同一 ID 无法被插入两次。
3. UPSERT 操作：利用数据库的 UPSERT（更新或插入）或类似逻辑。如果 ID 已存在，则忽略新数据；如果不存在，则插入新数据。
4. 状态机检查：在处理前，检查现有记录的状态。例如，如果一个 STOP 命令已经被成功处理，后续的重复 STOP 命令应被静默丢弃，而不是再次执行或覆盖。

事件顺序：为何「最后写入获胜」危险

Webhook 事件的到达顺序不保证与它们在源头发生的时间顺序一致。网络延迟、路由选择、服务器负载均衡等因素都可能导致事件乱序。例如，一个“已发送”状态的回调可能在“已送达”回调之前到达。如果你的接收器简单地按照接收到的顺序更新状态（“最后写入获胜”），那么一个稍后到达的、时间戳更早的“已发送”事件可能会覆盖掉一个更晚到达的、时间戳更晚的“已送达”事件，导致状态回滚。在处理任何事件前，务必比较其时间戳（或平台提供的单调递增序列号）与现有记录，以确定其是否为最新信息。尤其要警惕处理“已取消”或“已停止”状态的事件，它们必须优先于后续的“已发送”或“已送达”状态，以避免不合规的持续发送。

平台通常会在 2xx 响应（例如 200 OK）后的一秒内确认接收。然而，这仅表示平台收到了你的确认，并不代表你的内部处理已完成或无误。即使是成功的 2xx 响应，也可能因为网络瞬断导致平台未收到，从而触发重试。因此，你的服务器逻辑必须能够容忍并正确处理这些重试。

危险信号

• 忽视重试：“我们从不重试”（你会丢掉合规事件，尤其是在短时网络故障时）。
• 缺乏唯一 ID：没有事件 ID——只有时间戳（时间戳容易重复或被操纵）。
• 假设全局顺序：文档假定严格全局顺序（这是对现实的网络环境的严重误解）。
• 成本不可追踪：自动回复风暴却无线索进钱包（无法追踪成本，可能导致钱包耗尽）。
• 运维复杂性：运维要求第三方门户才能重放入站（增加了复杂性和延迟，且可能不提供幂等支持）。

从 IOSOR 开始

检查你的入站 webhook 日志，统计有多少事件 ID 到过两次以上。模拟回放一个重复事件和一个乱序事件（例如，先收到 failed，后收到 delivered）。接收端的目标是：确保每个事件只被处理一次，一个 STOP 命令只写入一次，钱包只被触碰一次。如果后写入的事件覆盖了之前的 STOP 状态，则视为失败。这就是接收幂等与重试顺序的体现，它不同于签名校验或入队前的网关锁。

在 IOSOR 控制台中，你可以清晰地看到每一条入站消息的完整生命周期，包括其状态、重试次数以及最终的处理结果。通过预付费钱包，你可以实时监控因自动回复等操作产生的费用。例如，当收到一个 STOP 命令时，系统会记录该事件 ID，并更新用户状态。如果同一 STOP 命令因重试而再次到达，幂等处理器会识别出该事件 ID 已被处理，并静默丢弃，避免重复扣款或状态回滚。对于乱序事件，例如一个“已发送”状态先于“已送达”到达，IOSOR 的幂等逻辑会根据时间戳或内部序列号判断，确保最终状态的准确性，不会让一个已送达的消息被错误地标记为“已发送”。这种机制确保了即使在复杂的网络条件下，核心业务逻辑也能稳健运行，保护预付费钱包免受意外支出，并确保合规性。

相关阅读: 入站自动回复循环抽钱包 · 使用入站缓冲区抵御运营商延迟激增 · 首次扣款前的预付资金预留.

IOSOR 要点

入站 webhook 会重试。接收幂等是唯一安全答案；顺序不是承诺。理解并利用平台的重试机制，同时通过严格的幂等设计来应对重复和乱序事件。确保所有与入站消息相关的操作，包括自动回复，都能在预付费钱包中得到清晰的追踪和管理。在 IOSOR 的控制台和预付费钱包视图中，你可以获得处理入站消息所需的全部可见性和控制力。

要做：给事件加唯一键，丢掉孪生件。不要：对 STOP 用后写覆盖，或对同一事件扣两次款。在 IOSOR 中，这意味着利用平台提供的唯一事件 ID，实现数据库级别的 UPSERT 操作，并始终优先处理表示用户意图终止服务的指令，即使它们比其他状态更新晚到。所有自动回复的成本都应实时反映在你的预付费钱包中，提供即时反馈，防止意外支出。利用 webhook 的 DLR（Delivery Report）和事件日志，结合幂等处理，构建一个健壮的入站消息接收系统。