Java Webhook 回调接收接口设计：验签、幂等和状态流转

支付通知、物流状态、代码托管事件、CRM 线索同步，很多系统都会通过 Webhook 把事件推给 Java 服务。回调接口看起来只是一个 POST，但如果没有验签、幂等和状态流转，线上很容易出现伪造请求、重复入库、状态倒退和重试风暴。

本文按 API 设计决策记录的方式，围绕 Java Webhook 接收接口说明：接口目标是什么，调用方需要什么响应，参数怎么设计，错误如何处理，旧版本如何兼容，并给出一套 Spring Boot 风格的示例。

接口目标：先接住事件，再异步处理业务

Webhook 接口的第一目标不是“立即完成所有业务逻辑”，而是安全、稳定地接收事件。接收阶段应该完成四件事：读取原始请求体，校验签名，记录事件，返回明确结果。真正的库存变更、订单状态同步、消息通知可以交给后续任务处理。

这样设计有两个好处：

• 第三方重试时，接口能快速判断事件是否已接收，避免重复处理。
• 业务处理失败时，可以在本系统内重放事件，不依赖第三方继续推送。

推荐的接收链路是：

第三方请求 -> 读取原始 body -> 验签 -> 幂等检查 -> 保存事件 -> 返回 200 -> 后台处理

注意“保存事件”和“处理业务”要分开。否则业务处理超时会拖慢回调响应，第三方可能认为通知失败并继续重试。

调用方需求：第三方只需要明确的接收结果

Webhook 调用方通常关心两件事：这次通知是否被接收，失败后是否需要重试。响应体不要设计得太复杂，状态要稳定。

{
  "code": "OK",
  "message": "accepted",
  "eventId": "evt_20260629_001"
}

对于已经接收过的事件，也可以返回成功：

{
  "code": "OK",
  "message": "duplicate accepted",
  "eventId": "evt_20260629_001"
}

这不是掩盖问题，而是 Webhook 接口的幂等语义：同一个事件重复送达，最终状态仍然是“本系统已接收”。重复通知不应该让调用方无限重试。

参数设计：事件 ID、时间戳、签名和业务载荷

一个可维护的 Webhook 请求，至少应该包含事件 ID、事件类型、时间戳、签名和业务载荷。签名字段建议放在请求头里，业务载荷放在 JSON body 中。

POST /api/webhooks/payment
X-Webhook-Event-Id: evt_20260629_001
X-Webhook-Timestamp: 1782725100
X-Webhook-Signature: sha256=...
Content-Type: application/json

{
  "eventType": "payment.succeeded",
  "occurredAt": "2026-06-29T17:25:00+08:00",
  "data": {
    "orderNo": "SO202606290001",
    "amount": "99.00",
    "currency": "CNY"
  }
}

设计时要明确每个字段的职责：

• eventId：幂等键，同一个事件全局唯一。
• timestamp：防止很久以前的请求被重放。
• signature：证明请求来自可信发送方。
• eventType：决定后续业务处理分支。
• data：只放业务载荷，不承担鉴权语义。

错误处理：验签失败、重复事件和业务失败要分层

Webhook 错误处理最容易混在一起。建议分三层：接收层错误、幂等层结果、业务层结果。

验签失败

验签失败说明请求不可信，应该直接拒绝，并记录安全日志。不要进入业务处理。

{
  "code": "INVALID_SIGNATURE",
  "message": "signature check failed"
}

重复事件

重复事件不是错误。只要本系统已经保存过同一个 eventId，就可以返回成功，并跳过重复入库。

业务失败

业务失败不一定要让第三方重试。更稳的做法是先保存事件，再把事件状态标记为 PROCESS_FAILED，由内部重试任务处理。这样第三方不会因为本系统短暂异常而反复推送。

兼容策略：新增字段不破坏旧回调

Webhook 事件会不断扩展。今天只有订单号和金额，明天可能增加优惠券、手续费、渠道信息。接收端不应该因为多了未知字段就失败。

兼容策略建议如下：

• 只对必要字段做强校验，例如 eventId、eventType、签名和时间戳。
• 业务载荷允许新增字段，反序列化时忽略未知字段。
• 事件类型新增时先进入 UNSUPPORTED_EVENT 状态，而不是直接丢弃。
• 保存原始 body，方便后续重放和排查。

Java 里可以给 DTO 增加忽略未知字段的配置：

@JsonIgnoreProperties(ignoreUnknown = true)
public class WebhookEvent {
    private String eventType;
    private OffsetDateTime occurredAt;
    private JsonNode data;

    public String getEventType() {
        return eventType;
    }

    public OffsetDateTime getOccurredAt() {
        return occurredAt;
    }

    public JsonNode getData() {
        return data;
    }
}

示例：Spring Boot 接收 Webhook 的最小骨架

下面示例保留关键结构：读取原始 body、拿请求头、验签、保存事件。真实项目里可以把验签和保存逻辑拆到服务层。

@RestController
@RequestMapping("/api/webhooks")
public class PaymentWebhookController {
    private final WebhookStore webhookStore;
    private final SignatureVerifier signatureVerifier;

    public PaymentWebhookController(WebhookStore webhookStore,
                                    SignatureVerifier signatureVerifier) {
        this.webhookStore = webhookStore;
        this.signatureVerifier = signatureVerifier;
    }

    @PostMapping("/payment")
    public ResponseEntity

存储层可以用唯一键保证幂等，例如 event_id 唯一。保存成功后，再由后台任务按 PENDING 状态拉取事件并处理。

总结

Java Webhook 接收接口的核心不是把业务逻辑塞进一个控制器，而是把接收、验签、幂等、存储和业务处理拆清楚。接口层只负责安全接收并返回稳定结果；存储层用事件 ID 保证幂等；后台任务负责状态流转和失败重试。这样第三方重复通知、网络抖动和业务短暂失败都不会把回调入口拖垮。