检查 Webhook 交付
确认应接收事件的端点
打开 Settings → Integrations → Webhooks。确认端点已启用并订阅了所需事件。账户 Webhook 权限涵盖整个账户的端点、密钥和交付日志；仅有 CRM 权限并不包含这些访问权限。
对于短信，请检查发送方 ID 选择。All Sender IDs 包含账户订阅的全部短信事件；选定列表会与原始短信发送方匹配。其他事件类型不受影响。
修改筛选条件不会重放历史事件
每次交付尝试（包括重试）都会检查发送方选择。修改不会重放旧事件，也不会改派已排队的交付。
查看交付尝试
交付日志显示时间、状态、事件、端点、HTTP 响应和错误。找到所查尝试对应的事件及端点，再与接收端日志对照。
没有匹配的尝试
先检查事件订阅、端点状态和短信发送方筛选条件，再排查接收端代码。
交付失败
通过 HTTP 响应或网络错误，判断接收链路中哪一层拒绝或未收到请求。
接收确认成功
另行检查应用处理情况。HTTP 确认并不能证明后续所有操作都已完成。
若防火墙限制入站请求，请使用账户设置中的最新交付 IP 列表。即使设置了 IP 白名单，也必须验证签名。
首先检查签名验证
IllyVoIP 发送 JSON POST 请求，其中包含 Illyvoip-Signature 请求头。处理事件前，请用 Webhook 密钥和原始请求体验证签名。
签名输入由时间戳、一个句点和原始请求体组成。验证前解析并重新编码 JSON 可能改变输入。准确的 HMAC SHA-256 步骤请参阅当前文档。
Webhook 签名密钥与客户 API 密钥不同。若已轮换签名密钥，请按正常凭据变更流程更新接收端。不要在支持日志中泄露任何密钥。
了解 HTTP 响应
任何 2xx
表示确认交付。空的 200 响应即可。
网络故障、无响应、408、429 或 5xx
可根据文档中的重试策略重试。
3xx 或其他 4xx
终止交付。请检查重定向、访问规则和接收端校验，不要等待自动重试。
及时确认有效事件，将耗时任务放入单独队列。接收端必须能够安全处理同一事件的多次接收。
使用事件 ID 避免重复处理
保存请求体中的 id，将其作为稳定的去重键。Illyvoip-Delivery 请求头标识交付任务，不能代替事件 ID。
短信关联方式请遵循当前发送响应和 Webhook 文档。交付任务 ID 与消息标识的用途不同。
需要帮助时，请提供事件 ID、尝试时间及其时区、响应码和已移除敏感信息的接收端错误。不要泄露签名密钥、API 密钥或无关事件内容。
创建、编辑和停用端点
在 Integrations → Webhooks 中选择 Add webhook，输入接收端 HTTPS URL，仅选择所需事件。按需检查短信发送方筛选条件，然后保存。显示签名密钥时请妥善保管；它不是账户 API 密钥。
在正确端点上使用 Edit 修改名称、事件订阅、筛选条件或启用状态。URL 为只读：若要更换 URL，请创建新端点，在接收端更新其签名密钥，准备好后再停用旧端点。测试前确认已保存的行。重复端点可能向同一接收端分别发送通知。删除旧端点前先确认哪个应用使用它；删除不会撤销已处理的事件。
协调签名密钥变更
只有准备好更新接收应用时才轮换密钥。阅读确认内容，安全保存新密钥并更新接收端，再依赖后续交付。不要假设旧密钥永远有效，也不要假设轮换会重放历史事件。交付日志仅用于近期排障，不是完整事件档案；请自行安全保存事件和处理记录。