Java接收Webhook重复通知时,如何实现幂等处理以避免业务重复执行?

发布人:A5数据发布时间:2026-11-17 10:45阅读量:2

Webhook 接收端不能把“收到一次 HTTP 请求”直接等同于“执行一次业务”。发送方可能因为超时、连接中断、响应丢失或内部重试,重复推送同一个事件;如果 Java 接口每次收到请求都直接扣款、改订单状态或发放权益,就会产生重复执行。

比较稳妥的实现方式是:先验证签名,再使用发送方提供的稳定事件 ID 做唯一约束,将通知保存到接收记录表;业务处理与接收记录放在同一个数据库事务中,重复事件查询到已成功状态后直接返回成功,不再执行第二次业务。对于邮件、调用第三方支付接口等数据库事务之外的副作用,则需要配合 Outbox 或下游幂等键。

先确定幂等键和处理边界

事件 ID优先于请求 ID

Webhook 通常包含以下几类标识:

  • 事件 ID:表示某一次业务事件,例如 payment_succeeded_12345。
  • 投递 ID:表示发送方进行的一次投递尝试,同一个事件可能有多个投递 ID。
  • 业务 ID:例如订单号、支付单号、用户 ID。

实现接收幂等时,优先使用发送方定义的稳定事件 ID。接收服务自己生成的 UUID、HTTP 请求时间和网络连接 ID,都不能作为重复判断依据,因为重试请求会生成新的值。

如果发送方的事件 ID只在单个业务类型内唯一,可以使用以下组合键:

(provider, event_type, event_id)

如果事件 ID在发送方全局唯一,则使用:

(provider, event_id)

不要直接使用订单号替代事件 ID。一个订单可能先后收到“已创建”“已支付”“已退款”等多个合法事件,它们的业务 ID相同,但不能被误判成同一条通知。

事件幂等和业务幂等不是一回事

事件 ID可以解决“同一条通知被重复投递”的问题,但不能解决“不同事件 ID表达同一次业务动作”的问题。

例如:

  • 发送方因为系统故障生成了两个不同的支付成功事件;
  • 一个事件来自支付回调,另一个来自对账任务;
  • 多个上游系统都可能触发同一个权益发放动作。

因此,通常需要两层保护:

  1. 接收层:使用事件 ID防止同一条 Webhook 重复处理。
  2. 业务层:使用订单号、支付单号或权益发放单号,防止同一业务动作被不同事件重复执行。

前者适合建立唯一索引,后者适合使用状态机、业务唯一索引或条件更新。

使用数据库唯一约束保存接收记录

下面的示例以 Java 17、Spring Boot 3.x、Spring JDBC、MySQL 8.0 为例。SignatureVerifier、PaymentWebhookParser 和 PaymentService 是项目中的自定义封装,实际接入时需要按照具体服务商的签名规则实现。

先创建接收记录表:

CREATE TABLE webhook_inbox (
    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
    provider VARCHAR(64) NOT NULL,
    event_id VARCHAR(128) NOT NULL,
    payload_hash CHAR(64) NOT NULL,
    payload LONGBLOB NOT NULL,
    status VARCHAR(20) NOT NULL,
    attempts INT NOT NULL DEFAULT 0,
    last_error VARCHAR(1000) NULL,
    created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
    updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6)
        ON UPDATE CURRENT_TIMESTAMP(6),
    PRIMARY KEY (id),
    UNIQUE KEY uk_provider_event (provider, event_id),
    KEY ix_webhook_status_time (status, created_at)
) ENGINE = InnoDB
  DEFAULT CHARSET = utf8mb4;

几个字段的作用如下:

字段作用
provider区分不同发送方,避免不同系统使用相同事件 ID时冲突
event_id发送方提供的稳定事件标识
payload_hash检测同一个事件 ID对应的内容是否发生变化
payload保存原始请求体,便于审计、重放和排查
status记录处理结果,例如 RECEIVED、SUCCESS、FAILED_FINAL
attempts记录尝试次数,便于识别持续失败的事件
last_error保存最后一次可供排查的错误信息

UNIQUE KEY uk_provider_event 是幂等实现的底线。应用代码中的“先查询、再插入”不能替代唯一约束,因为两个并发请求可能同时查询不到记录,然后同时执行后续业务。

插入时不要覆盖第一次收到的内容

可以使用 MySQL 的 ON DUPLICATE KEY UPDATE,在重复事件到来时保持原记录不变:

@Repository
public class WebhookRepository {

    private final JdbcTemplate jdbcTemplate;

    public WebhookRepository(JdbcTemplate jdbcTemplate) {
        this.jdbcTemplate = jdbcTemplate;
    }

    public void insertIfAbsent(
            String provider,
            String eventId,
            String payloadHash,
            byte[] payload
    ) {
        jdbcTemplate.update("""
            INSERT INTO webhook_inbox
                (provider, event_id, payload_hash, payload, status, attempts)
            VALUES (?, ?, ?, ?, 'RECEIVED', 0)
            ON DUPLICATE KEY UPDATE id = id
            """,
            provider,
            eventId,
            payloadHash,
            payload
        );
    }

    public WebhookEvent findForUpdate(String provider, String eventId) {
        return jdbcTemplate.queryForObject("""
            SELECT id, provider, event_id, payload_hash, payload, status
            FROM webhook_inbox
            WHERE provider = ? AND event_id = ?
            FOR UPDATE
            """,
            (rs, rowNum) -> new WebhookEvent(
                rs.getLong("id"),
                rs.getString("provider"),
                rs.getString("event_id"),
                rs.getString("payload_hash"),
                rs.getBytes("payload"),
                rs.getString("status")
            ),
            provider,
            eventId
        );
    }

    public void markSuccess(long id) {
        jdbcTemplate.update("""
            UPDATE webhook_inbox
            SET status = 'SUCCESS',
                attempts = attempts + 1,
                last_error = NULL
            WHERE id = ?
            """, id);
    }

    public void markFinalFailure(long id, String errorMessage) {
        jdbcTemplate.update("""
            UPDATE webhook_inbox
            SET status = 'FAILED_FINAL',
                attempts = attempts + 1,
                last_error = ?
            WHERE id = ?
            """, errorMessage, id);
    }
}

payload 使用 LONGBLOB 是为了保存接收到的原始字节。某些服务商的签名是基于原始请求体计算的,如果先解析 JSON、重新格式化后再验签,可能造成签名不一致。

如果使用 PostgreSQL,可以把插入语句替换为:

INSERT INTO webhook_inbox
    (provider, event_id, payload_hash, payload, status, attempts)
VALUES (?, ?, ?, ?, 'RECEIVED', 0)
ON CONFLICT (provider, event_id) DO NOTHING;

核心原则不变:应用层判断之前,数据库必须先具备唯一约束。

在 Spring 中实现同步幂等处理

同步处理适合以下情况:

  • 业务更新主要发生在同一个数据库中;
  • 处理耗时较短;
  • 不需要在数据库事务中直接调用长时间运行的外部接口;
  • 发送方的超时时间能够覆盖正常处理时长。

先定义接收结果和事件对象:

public enum ReceiveResult {
    PROCESSED,
    DUPLICATE,
    REJECTED_FINAL,
    PAYLOAD_CONFLICT
}
public record WebhookEvent(
        long id,
        String provider,
        String eventId,
        String payloadHash,
        byte[] payload,
        String status
) {
}

接收服务的关键代码如下:

@Service
public class WebhookService {

    private final WebhookRepository repository;
    private final PaymentWebhookParser parser;
    private final PaymentService paymentService;

    public WebhookService(
            WebhookRepository repository,
            PaymentWebhookParser parser,
            PaymentService paymentService
    ) {
        this.repository = repository;
        this.parser = parser;
        this.paymentService = paymentService;
    }

    @Transactional
    public ReceiveResult handle(
            String provider,
            String eventId,
            byte[] rawBody
    ) {
        String currentHash = sha256(rawBody);

        repository.insertIfAbsent(
                provider,
                eventId,
                currentHash,
                rawBody
        );

        WebhookEvent stored =
                repository.findForUpdate(provider, eventId);

        if (!stored.payloadHash().equals(currentHash)) {
            // 不覆盖原始内容,也不执行这次请求携带的业务数据
            return ReceiveResult.PAYLOAD_CONFLICT;
        }

        if ("SUCCESS".equals(stored.status())) {
            return ReceiveResult.DUPLICATE;
        }

        if ("FAILED_FINAL".equals(stored.status())) {
            return ReceiveResult.REJECTED_FINAL;
        }

        PaymentCommand command;

        try {
            command = parser.parse(stored.payload());
        } catch (InvalidWebhookException ex) {
            repository.markFinalFailure(
                    stored.id(),
                    truncate(ex.getMessage())
            );
            return ReceiveResult.REJECTED_FINAL;
        }

        /*
         * 这里必须加入当前事务。
         * 不要在 PaymentService 中使用 REQUIRES_NEW,
         * 否则业务写入可能独立提交,无法与 SUCCESS 状态保持原子性。
         */
        paymentService.apply(command);

        repository.markSuccess(stored.id());

        return ReceiveResult.PROCESSED;
    }

    private static String sha256(byte[] input) {
        try {
            byte[] digest = MessageDigest
                    .getInstance("SHA-256")
                    .digest(input);
            return HexFormat.of().formatHex(digest);
        } catch (NoSuchAlgorithmException ex) {
            throw new IllegalStateException("SHA-256 is unavailable", ex);
        }
    }

    private static String truncate(String message) {
        if (message == null) {
            return "invalid webhook";
        }
        return message.length() <= 1000
                ? message
                : message.substring(0, 1000);
    }
}

示例使用了以下 JDK 类:

import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.HexFormat;

@Transactional 使用 Spring 的:

import org.springframework.transaction.annotation.Transactional;

这里的执行顺序很重要:

在 Spring 中实现同步幂等处理配图

  1. 使用唯一索引插入事件记录,已存在时不覆盖原数据。
  2. 使用 SELECT ... FOR UPDATE 锁住这条事件记录。
  3. 比较当前请求的内容摘要与第一次保存的摘要。
  4. 如果状态已经是 SUCCESS,直接返回重复结果。
  5. 解析事件并执行本地业务更新。
  6. 业务更新成功后,将接收记录更新为 SUCCESS。
  7. 整个过程提交数据库事务。

两个相同事件并发到达时,第二个事务会在唯一索引或行锁处等待。第一个事务提交后,第二个事务读取到 SUCCESS,不会再次执行 paymentService.apply。

业务更新必须加入同一个事务

PaymentService 中的数据库写入应该加入外层事务:

@Service
public class PaymentService {

    private final PaymentRepository paymentRepository;

    public PaymentService(PaymentRepository paymentRepository) {
        this.paymentRepository = paymentRepository;
    }

    public void apply(PaymentCommand command) {
        int affectedRows = paymentRepository.markPaid(
                command.paymentId(),
                command.paidAt()
        );

        if (affectedRows == 0) {
            PaymentState current =
                    paymentRepository.findState(command.paymentId());

            if (current == null) {
                throw new RetryableBusinessException(
                        "payment does not exist yet"
                );
            }

            if (current == PaymentState.PAID) {
                // 可能是同一业务动作已经通过其他事件完成
                return;
            }

            throw new InvalidWebhookException(
                    "payment state cannot move to PAID"
            );
        }
    }
}

业务表中的更新也应该表达状态约束,而不是无条件覆盖。例如:

UPDATE payment_order
SET status = 'PAID',
    paid_at = ?
WHERE payment_id = ?
  AND status IN ('CREATED', 'AUTHORIZED');

如果返回行数为 0,不能直接当成数据库错误。需要继续判断:

  • 支付单不存在:可能是数据尚未同步,适合重试;
  • 当前状态已经是 PAID:可以视为业务幂等成功;
  • 当前状态是 REFUNDED 或 CLOSED:可能是乱序或非法状态转换,需要告警;
  • 数据库连接失败:事务回滚,并让发送方稍后重试。

paymentService.apply 抛出可重试异常时,不要把事件标记为成功。让异常从 @Transactional 方法抛出,事务会回滚,控制器可以返回 5xx。这样发送方重试时,事件仍然能够重新进入处理流程。

控制器中先验签,再执行幂等逻辑

控制器应当先验证签名,再将事件交给业务服务。不能为了“快速去重”而在验签之前信任请求中的事件 ID。

@RestController
@RequestMapping("/api")
public class WebhookController {

    private final WebhookService webhookService;
    private final SignatureVerifier signatureVerifier;

    public WebhookController(
            WebhookService webhookService,
            SignatureVerifier signatureVerifier
    ) {
        this.webhookService = webhookService;
        this.signatureVerifier = signatureVerifier;
    }

    @PostMapping(
            value = "/webhooks/{provider}",
            consumes = MediaType.ALL_VALUE
    )
    public ResponseEntity<Void> receive(
            @PathVariable String provider,
            @RequestHeader(value = "X-Event-Id", required = false)
            String eventId,
            @RequestHeader(value = "X-Signature", required = false)
            String signature,
            @RequestBody byte[] rawBody
    ) {
        if (eventId == null || eventId.isBlank()
                || signature == null || signature.isBlank()) {
            return ResponseEntity.badRequest().build();
        }

        if (!signatureVerifier.verify(
                provider, eventId, rawBody, signature
        )) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
                    .build();
        }

        ReceiveResult result = webhookService.handle(
                provider,
                eventId,
                rawBody
        );

        return switch (result) {
            case PROCESSED, DUPLICATE, REJECTED_FINAL ->
                    ResponseEntity.ok().build();

            case PAYLOAD_CONFLICT ->
                    ResponseEntity.status(HttpStatus.CONFLICT).build();
        };
    }
}

SignatureVerifier 的接口可以定义为:

public interface SignatureVerifier {

    boolean verify(
            String provider,
            String eventId,
            byte[] rawBody,
            String signature
    );
}

签名算法、密钥读取方式、时间戳窗口和签名头名称都依赖具体发送方,不能用一个固定实现套用所有 Webhook。验签时还应使用常量时间比较,避免把签名字符串直接使用普通字符串比较。

对于可重试的数据库异常或业务异常,可以通过 @RestControllerAdvice 统一返回 503。由于异常已经从事务代理中抛出,接收记录和业务更新会一起回滚:

@RestControllerAdvice
public class WebhookExceptionHandler {

    @ExceptionHandler(RetryableBusinessException.class)
    public ResponseEntity<Void> handleRetryable(
            RetryableBusinessException ex
    ) {
        return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
                .build();
    }

    @ExceptionHandler(DataAccessException.class)
    public ResponseEntity<Void> handleDatabaseFailure(
            DataAccessException ex
    ) {
        return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
                .build();
    }
}

返回码需要结合发送方规则调整:

情况是否执行业务常见处理
签名错误否返回 401,不写入业务记录
必填字段缺失否返回 400,或记录为最终失败
同一事件已成功否返回 2xx,停止发送方重试
数据库暂时不可用否或事务回滚返回 5xx,等待重试
业务数据暂时不存在否返回 5xx或进入持久化重试队列
同一事件 ID但内容不同否拒绝处理并告警
业务状态不允许转换否记录最终失败,不应反复重试

永久失败是否返回 2xx,需要查看发送方的重试约定。有些服务商收到 4xx 仍会继续重试;如果已经确认事件内容有效但业务上无法处理,可以先写入 FAILED_FINAL,再返回发送方认可的 2xx,避免无休止重试。

处理长任务和外部副作用

同步事务不适合把以下操作直接放在数据库事务中:

  • 调用支付、库存或会员系统;
  • 发送邮件、短信和站内信;
  • 生成大文件;
  • 等待第三方接口返回;
  • 处理时间可能超过 Webhook 超时窗口的任务。

原因是数据库事务无法回滚已经发生的网络副作用。例如:

  1. Java 服务调用第三方接口成功;
  2. 第三方动作已经完成;
  3. Java 服务在更新 webhook_inbox 前进程崩溃;
  4. 发送方重试,服务再次调用第三方接口。

这时单纯依靠数据库唯一索引已经不够。

接收记录与业务处理分离

长任务可以改为以下流程:

接收记录与业务处理分离配图

  1. 验证签名并将事件写入 webhook_inbox;
  2. 接收事务提交后返回 2xx;
  3. 定时任务、消息消费者或任务队列读取 RECEIVED 记录;
  4. 使用条件更新把状态改为 PROCESSING;
  5. 执行业务处理;
  6. 成功后更新为 SUCCESS;
  7. 失败时记录 last_error 和下一次重试时间。

抢占任务时使用条件更新:

UPDATE webhook_inbox
SET status = 'PROCESSING',
    attempts = attempts + 1,
    updated_at = CURRENT_TIMESTAMP(6)
WHERE id = ?
  AND status IN ('RECEIVED', 'RETRY');

只有返回值为 1 的消费者获得处理资格,返回值为 0 表示其他消费者已经处理或正在处理这条记录。生产环境通常还要增加 lease_until 或处理令牌,用于回收消费者崩溃后遗留的 PROCESSING 记录。

状态回收不能简单地把所有长时间未完成的任务立即重置。处理时间较长时,应设置大于正常处理时长的租约,或者增加续租机制。即使如此,业务表仍应使用唯一约束或状态条件更新作为第二层保护,因为进程可能在租约到期附近暂停。

使用 Outbox 保证数据库动作可恢复

如果 Webhook 处理需要更新本地订单并发送通知,可以在同一个本地事务中同时写订单表和 Outbox 表:

CREATE TABLE webhook_outbox (
    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
    dedupe_key VARCHAR(200) NOT NULL,
    event_type VARCHAR(64) NOT NULL,
    payload LONGBLOB NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'PENDING',
    created_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
    updated_at DATETIME(6) NOT NULL DEFAULT CURRENT_TIMESTAMP(6)
        ON UPDATE CURRENT_TIMESTAMP(6),
    PRIMARY KEY (id),
    UNIQUE KEY uk_outbox_dedupe (dedupe_key)
) ENGINE = InnoDB
  DEFAULT CHARSET = utf8mb4;

例如,订单更新和 Outbox 写入使用同一个事务:

使用 Outbox 保证数据库动作可恢复配图

订单状态:UNPAID -> PAID
Outbox:
dedupe_key = payment:provider-a:event-123:notify-order
status = PENDING

之后由独立发送器读取 PENDING 记录并发送通知。发送器即使因为超时而重复发送,也不会重复创建 Outbox 记录。

如果下游接口支持幂等键,应把组合值作为请求头或请求参数发送:

payment:provider-a:event-123:notify-order

如果下游不支持幂等键,就无法仅靠本地数据库保证网络调用的严格一次效果。此时应优先使用下游查询接口进行结果确认,并设计对账和人工补偿流程,而不是把“发送成功后更新发送状态”当成绝对可靠的方案。

不要把 Redis 锁当成完整幂等方案

常见的替代实现是:

SET webhook:{eventId} processing NX EX 300

Redis 可以减少短时间内的并发处理,但单独使用时有明显边界:

  • 锁的 TTL 到期后,原任务可能仍未结束;
  • 服务在业务执行完成、删除锁之前崩溃,重试仍可能再次执行;
  • 只保存锁而不保存结果,无法判断事件是否已经成功;
  • Redis 与业务数据库不是同一事务,可能出现状态不一致;
  • 过短的 TTL 会误释放,过长的 TTL 会拖延恢复。

因此 Redis 更适合作为降低并发压力的辅助组件,而不应替代数据库唯一约束和业务状态记录。消息队列也不能自动提供业务幂等,绝大多数队列仍然需要消费者自行处理重复投递。

乱序通知需要单独处理

幂等只能回答“同一事件是否重复”,不能回答“事件是否按正确顺序到达”。

例如订单先收到:

ORDER_PAID

之后因为网络延迟又收到:

ORDER_CREATED

如果每条事件都直接覆盖订单状态,最终状态可能被错误地改回创建中。

可以在业务表中保存版本号、事件序号或状态等级,并只允许合法的单向转换:

UPDATE order_record
SET status = ?,
    event_version = ?
WHERE order_id = ?
  AND event_version < ?;

或者在 Java 中根据状态机判断:

CREATED -> AUTHORIZED -> PAID -> REFUNDED

收到较旧版本的事件时,可以记录为已接收但不改变当前状态。收到未知版本、跳跃过大的版本或不允许的逆向转换时,应进入异常记录,等待对账,而不是盲目覆盖现有数据。

乱序通知需要单独处理配图

用并发和异常场景验证结果

不要只发送一次正常请求来判断幂等是否生效。可以准备以下验证场景。

重复并发投递

使用同一个 provider、event_id 和请求体,同时发送多次请求。预期结果是:

  • webhook_inbox 中只有一行;
  • 业务表只发生一次有效状态变化;
  • 后续请求返回 2xx;
  • 日志能区分 PROCESSED 与 DUPLICATE。

可以通过查询确认:

SELECT
    provider,
    event_id,
    status,
    attempts,
    created_at,
    updated_at
FROM webhook_inbox
WHERE provider = 'payment-provider'
  AND event_id = 'event-123';

响应丢失后的重试

在业务事务提交后模拟客户端断开或丢弃响应,然后再次发送同一个事件。预期结果是第二次请求读取到 SUCCESS,不再执行扣款、发货或发放权益。

处理过程中抛出异常

在业务更新前后分别注入一次可重试异常,检查:

  • 业务表是否回滚;
  • 事件是否仍能被重试;
  • 是否错误地留下了 SUCCESS;
  • 重试成功后是否只有一次业务结果。

对于本地数据库事务,业务更新和 SUCCESS 标记应当一起提交或一起回滚。若两者出现分离,通常说明使用了独立事务、异步线程或外部副作用,需要重新划分处理边界。

相同事件 ID对应不同内容

发送相同事件 ID但修改金额、订单号或状态字段的请求。预期结果是:

  • 不覆盖第一次保存的原始请求体;
  • 不执行第二次业务;
  • 记录内容冲突;
  • 触发告警或进入人工核对流程。

payload_hash 是否基于原始 JSON 字节计算,要根据发送方协议决定。如果服务商保证重试时原始请求体完全一致,可以直接使用原始字节摘要;如果服务商可能改变 JSON 空白、字段顺序但事件内容不变,则应在验签后按约定解析并生成规范化摘要,同时保留原始请求体用于审计。

验证日志字段

建议每次处理至少记录以下字段:

provider=payment-provider
event_id=event-123
business_id=order-456
result=DUPLICATE
status_before=SUCCESS
attempt=2
trace_id=...

日志中的 event_id、业务 ID和处理结果要保持一致,便于从一次重复通知追踪到业务表、Outbox 和下游调用。

接入完成后,真正需要确认的不是接口返回了几次 200,而是同一个事件经过重复投递、并发到达、响应丢失和短暂故障后,业务状态仍然只有一次有效变化;对于跨数据库或跨服务的动作,则应继续检查 Outbox、下游幂等键和对账流程是否形成闭环。

围绕这类Webhook接收、数据库写入与异步任务处理,A5idc数据可提供用于业务接口和数据服务部署的香港、美国、日本等地区物理服务器,结合SSD或NVMe存储承载接收记录、业务数据与Outbox等应用数据;域名与SSL证书可用于建立HTTPS接口入口,CDN则可按业务需要承担站点静态资源分发和源站流量分担,便于企业按访问地区组织应用运行环境。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/9928.html

相关推荐