概述
好停Webhook机制允许您的系统实时接收停车场业务事件通知，无需轮询API。当指定事件发生时，好停服务器会主动向您配置的回调地址发送HTTP POST请求，推送JSON格式的事件数据。这种机制适用于需要实时响应的场景，如入场自动开闸、支付成功通知、订单状态同步等。Webhook采用异步推送模式，保证事件不丢失，并支持失败重试。
支持的事件类型
好停目前支持以下事件类型。入场事件（vehicle.enter）：当车辆驶入停车场时触发，推送数据包含parking_lot_id、plate_number、enter_time、entry_gate、vehicle_image_url字段。出场事件（vehicle.exit）：当车辆驶出停车场时触发，推送数据包含order_id、plate_number、exit_time、exit_gate、parking_duration、total_fee字段。
支付成功事件（payment.success）：当停车费用支付成功时触发，推送数据包含order_id、plate_number、payment_method、payment_amount、payment_time、transaction_id字段。订单完成事件（order.completed）：当订单完整结束（支付并出场）时触发，推送数据包含完整的订单信息，包括入场时间、出场时间、停车时长、计费明细、支付信息等全部字段。
此外还支持：车位变化事件（space.changed），当车位占用状态变化时触发；设备告警事件（device.alert），当相机或道闸设备异常时触发；月卡到期事件（monthly_pass.expiring），在月卡到期前7天和1天触发提醒。
回调地址配置
在好停开发者后台的Webhook配置页面，您可以添加和管理回调地址。每个回调地址需要配置以下信息：回调URL必须是公网可访问的HTTPS地址（不支持HTTP），支持同时配置多个回调地址以实现负载或分环境通知，可以为每个地址选择订阅的事件类型（如只订阅支付事件）。配置保存后，好停会发送一个验证请求到您的回调地址，您需要在5秒内返回HTTP 200状态码以完成验证，验证请求的body中包含challenge字段，您需要原样返回该字段。
建议为不同环境配置不同的回调地址（如开发环境https://dev.yourdomain.com/webhook、测试环境https://test.yourdomain.com/webhook、生产环境https://api.yourdomain.com/webhook），并为每个地址配置独立的签名密钥以提高安全性。
签名验证机制
为保证推送数据的安全性，每个Webhook请求都包含签名信息用于验证请求来源和数据完整性。签名算法为HMAC-SHA256，使用您配置的签名密钥对请求体（原始JSON字符串）进行签名。签名值通过请求头X-ParkingLink-Signature传递，时间戳通过X-ParkingLink-Timestamp传递（Unix毫秒时间戳）。
您的服务器收到Webhook请求后，应按以下步骤验证签名：取出请求体的原始字节内容，使用相同的HMAC-SHA256算法和密钥对请求体计算签名，将计算结果与请求头中的签名值进行恒定时间比较（防止时序攻击）。如果一致则验证通过，处理业务逻辑；如果不一致则拒绝请求并返回401状态码。建议同时验证时间戳与当前时间的差值不超过5分钟，防止重放攻击。
重试策略
如果您的回调地址未能正常响应（非2xx状态码或超时），好停会自动进行重试。重试策略：第1次失败后10秒重试，第2次失败后30秒重试，第3次失败后60秒重试，第4次失败后300秒（5分钟）重试，第5次失败后1800秒（30分钟）重试。共5次重试，全部失败后该事件将被标记为推送失败。您可以在开发者后台查看推送失败的事件列表，手动触发重新推送。
测试方法
好停开发者后台提供Webhook测试工具。在Webhook配置页面，选择要测试的事件类型，点击发送测试按钮，系统会向您的回调地址发送一条测试事件。测试事件的数据字段与真实事件一致，但会在请求头X-ParkingLink-Test中标记为true，方便您在代码中区分测试和真实事件。建议在正式上线前，对所有订阅的事件类型都进行完整的测试验证，确保每个事件的解析和处理逻辑都正确无误。测试通过后，建议先在灰度环境运行1-2天，确认推送稳定无异常后再全量上线到生产环境部署。