UD5工具箱
Webhook
Webhook是一种HTTP回调机制，允许一个应用（发送方）在特定事件发生时主动向另一个应用（接收方）发送HTTP请求。与传统的轮询（Polling）方式不同，Webhook采用事件驱动的推送模式，只有在事件发生时才发送请求，大大减少了不必要的网络流量和服务器负载。Webhook的工作流程如下：接收方注册一个URL（Webhook端点）到发送方 -> 发送方在事件发生时向该URL发送POST请求 -> 接收方处理请求并返回响应。Webhook广泛应用于各种场景：版本控制平台（GitHub、GitLab）通知代码变更、支付平台（Stripe、PayPal）通知支付结果、通讯平台（Slack、Discord）集成机器人消息、电商平台（Shopify、WooCommerce）通知订单状态变更、监控工具（PagerDuty、Datadog）发送告警通知。Webhook的URL需要是公开可访问的，因为发送方需要能够向该URL发送请求。Webhook的请求格式通常为JSON或表单数据，具体格式取决于发送方的实现。接收方需要正确处理请求的格式和内容，并返回适当的HTTP状态码（通常是200或2xx）表示接收成功。
Webhook端点（Endpoint）
Webhook端点是接收Webhook请求的URL地址，也称为Webhook URL。它是Webhook机制的核心组件之一。一个有效的Webhook端点需要满足以下条件：URL必须是公开可访问的（发送方需要能够发起HTTP请求）；必须支持HTTP/HTTPS协议（推荐使用HTTPS以确保数据传输安全）；必须能够处理POST请求（大多数Webhook使用POST方法）；必须返回适当的HTTP状态码（通常是200-299表示成功接收）。Webhook端点的设计需要注意以下事项：端点应该是幂等的，即多次接收到相同事件应该产生相同的结果（因为发送方可能重试）；端点应该快速响应（通常在5秒内），避免长时间处理导致超时；端点应该验证请求的来源（如使用签名验证），防止伪造请求；端点应该处理各种HTTP方法和Content-Type，保持健壮性。在开发阶段，可以使用本工具提供的临时URL作为Webhook端点进行测试。在生产环境中，应该使用HTTPS端点并实现完善的错误处理和验证机制。
HTTP方法在Webhook中的使用
Webhook请求通常使用HTTP POST方法，这是行业惯例。POST方法用于向服务器提交数据，Webhook的请求体中包含事件的详细信息。虽然HTTP规范允许使用其他方法，但几乎所有主流Webhook平台（GitHub、Stripe、Twilio、微信支付等）都使用POST方法。某些Webhook平台也支持GET方法，用于发送简单的通知或验证端点的可用性。GET请求不包含请求体，所有信息都通过URL查询参数传递。PUT方法在Webhook中较少使用，但某些RESTful API的Webhook可能使用PUT来表示资源更新。DELETE方法在Webhook中几乎不使用。HEAD方法用于检查端点是否可用，但不返回响应体。OPTIONS方法用于CORS预检请求，与Webhook本身的通信无关。在调试Webhook时，注意查看请求方法以确认发送方的行为是否符合文档规范。如果收到非POST方法的Webhook请求，可能需要检查发送方的配置或版本兼容性。
Webhook载荷（Payload）
Webhook载荷是Webhook请求体中包含的数据，通常以JSON格式传输。载荷包含了事件的详细信息，其结构取决于发送方的实现。典型的Webhook载荷包含以下字段：event_type或action（事件类型，如push、payment_success、order_created）、timestamp或created_at（事件发生的时间戳）、data或payload（事件相关的数据对象，包含具体的业务信息）、id或event_id（事件的唯一标识符，用于去重和追踪）、metadata或context（额外的元数据，如版本号、请求ID等）。不同平台的载荷格式差异很大：GitHub的载荷包含repository、sender、commits等字段；Stripe的载荷包含type、data.object等嵌套结构；微信支付的载荷使用XML格式而非JSON。载荷的大小通常有限制（如GitHub最大25MB），超大的载荷会被截断或拒绝。在调试Webhook时，仔细检查载荷的结构和字段是否符合平台文档的规范。注意日期时间格式（ISO 8601 vs Unix时间戳）、数字精度（大整数在JavaScript中的精度问题）和编码格式（UTF-8）等常见问题。
Webhook签名验证
Webhook签名验证是确保Webhook请求来源可信的安全机制。由于Webhook端点是公开的，任何人都可能向端点发送伪造的请求。签名验证通过在请求中添加一个由发送方和接收方共享的密钥（Secret）生成的签名，接收方使用相同的密钥验证签名来确认请求的真实性。常见的签名验证方式有以下几种。HMAC-SHA256：发送方使用密钥和请求体生成HMAC-SHA256签名，放在请求头中（如X-Hub-Signature-256）。接收方使用相同密钥重新计算签名并比对。GitHub和Stripe使用这种方式。简单的哈希验证：发送方对请求体进行MD5或SHA-1哈希，放在请求头中。安全性较低，不推荐。时间戳+签名：在签名中包含时间戳，接收方验证时间戳的有效期（如5分钟内），防止重放攻击。JWT：使用JSON Web Token格式传递签名信息，支持更复杂的验证逻辑。在调试Webhook时，检查请求头中的签名字段（如X-Hub-Signature-256、Stripe-Signature），使用平台提供的密钥验证签名。如果签名验证失败，可能是密钥不匹配、请求被篡改或中间人攻击。
Webhook重试机制
当Webhook请求失败时（如接收方返回非2xx状态码、连接超时、DNS解析失败等），发送方通常会自动重试。重试机制是Webhook可靠性的重要保障。不同的发送方有不同的重试策略。GitHub的重试策略：如果Webhook在10秒内没有返回2xx响应，GitHub会标记为失败并在5分钟后重试，最多重试3次（共4次尝试），间隔逐渐增加（5分钟、30分钟、2小时）。Stripe的重试策略：最多重试15天，间隔从几分钟到几天不等，具体取决于失败类型。微信支付的重试策略：根据错误码决定重试次数和间隔，通常在24小时内重试多次。Twilio的重试策略：最多重试48小时，间隔从1分钟到数小时不等。由于重试机制的存在，接收方必须实现幂等性（Idempotency），即多次接收到相同事件应该产生相同的结果。实现幂等性的常见方式：使用事件ID（如GitHub的X-GitHub-Delivery）作为去重键，在处理前检查是否已经处理过该事件。如果接收到重复事件，返回200状态码但不重复处理业务逻辑。
Webhook vs 普通API调用
Webhook和普通API调用是两种不同的通信模式，各有特点和适用场景。普通API调用是主动模式：客户端主动向服务器发起请求，获取或修改数据。客户端控制请求的时机和频率，服务器被动响应。典型的API调用场景：用户点击按钮触发数据查询、定时任务轮询获取最新数据、批量操作逐条调用API。Webhook是被动模式：服务器在事件发生时主动向客户端（Webhook端点）发送请求。服务器控制请求的时机，客户端被动接收。典型的Webhook场景：支付完成后通知商户、代码push后触发CI/CD、订单状态变更通知下游系统。关键区别：触发方式（主动请求 vs 被动接收）、实时性（轮询延迟 vs 实时推送）、服务器负载（持续轮询 vs 按需推送）、实现复杂度（客户端需要轮询逻辑 vs 服务器需要推送逻辑）。在选择通信模式时，考虑以下因素：数据更新频率（高频变化适合Webhook，低频变化适合轮询）、实时性要求（强实时性适合Webhook）、服务器能力（能否支持Webhook推送）、网络环境（NAT、防火墙是否允许入站连接）。
Webhook数据保留与过期
Webhook数据的保留策略取决于接收端的实现。使用本工具时，捕获的Webhook数据保存在webhook.site的服务器上，通常保留7天后自动删除。工具本身不永久存储任何数据，所有请求记录都保存在浏览器的内存中（页面关闭后丢失）。在生产环境中，Webhook数据的保留策略需要根据业务需求制定。常见的保留策略包括：短期保留（如7-30天，适用于日志和审计）、长期保留（如90天以上，适用于合规和分析）、永久保留（适用于核心业务数据）。数据保留时需要考虑以下因素：存储成本（大量Webhook数据会占用存储空间）、隐私合规（GDPR等法规对个人数据保留有要求）、查询性能（历史数据过多会影响查询效率）、备份策略（是否需要备份历史Webhook数据）。建议的做法：将重要的Webhook事件存储到数据库中，设置合理的数据保留期限，定期清理过期数据。对于测试环境，使用本工具的临时存储即可，测试完成后清空记录。