Java接收Webhook重复通知时,如何实现幂等处理以避免业务重复执行?
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表达同一次业务动作”的问题。
例如:
- 发送方因为系统故障生成了两个不同的支付成功事件;
- 一个事件来自支付回调,另一个来自对账任务;
- 多个上游系统都可能触发同一个权益发放动作。
因此,通常需要两层保护:
- 接收层:使用事件 ID防止同一条 Webhook 重复处理。
- 业务层:使用订单号、支付单号或权益发放单号,防止同一业务动作被不同事件重复执行。
前者适合建立唯一索引,后者适合使用状态机、业务唯一索引或条件更新。
使用数据库唯一约束保存接收记录
下面的示例以 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;
这里的执行顺序很重要:

- 使用唯一索引插入事件记录,已存在时不覆盖原数据。
- 使用
SELECT ... FOR UPDATE锁住这条事件记录。 - 比较当前请求的内容摘要与第一次保存的摘要。
- 如果状态已经是
SUCCESS,直接返回重复结果。 - 解析事件并执行本地业务更新。
- 业务更新成功后,将接收记录更新为
SUCCESS。 - 整个过程提交数据库事务。
两个相同事件并发到达时,第二个事务会在唯一索引或行锁处等待。第一个事务提交后,第二个事务读取到 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 超时窗口的任务。
原因是数据库事务无法回滚已经发生的网络副作用。例如:
- Java 服务调用第三方接口成功;
- 第三方动作已经完成;
- Java 服务在更新
webhook_inbox前进程崩溃; - 发送方重试,服务再次调用第三方接口。
这时单纯依靠数据库唯一索引已经不够。
接收记录与业务处理分离
长任务可以改为以下流程:

- 验证签名并将事件写入
webhook_inbox; - 接收事务提交后返回 2xx;
- 定时任务、消息消费者或任务队列读取
RECEIVED记录; - 使用条件更新把状态改为
PROCESSING; - 执行业务处理;
- 成功后更新为
SUCCESS; - 失败时记录
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 写入使用同一个事务:

订单状态: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



