Laravel 中如何将Webhook接收的JSON格式支付详情存入数据库

Laravel 框架下Webhook支付数据正确存储实操
前置路由配置
- 所有支付渠道的Webhook路由必须跳过CSRF校验:打开
app/Http/Middleware/VerifyCsrfToken.php,把对应路由路径加入$except排除数组,否则第三方发起的无CSRF令牌的请求会被直接返回419错误 - 路由不要挂载认证中间件:Webhook是支付平台主动发起的服务端请求,不存在用户登录态,按常规API路由配置即可,示例:
// routes/api.php 中配置 Route::post('/webhook/alipay', [PaymentWebhookController::class, 'handleAlipayNotify']);
接收原始JSON payload的正确方式
很多开发容易在这里踩坑,直接用$request->all()或者$request->input()取值,往往会因为请求头的Content-Type不匹配取不到完整数据:
- 优先读取请求原始内容:
$rawPayload = $request->getContent();这一步能拿到所有渠道不管什么编码格式发过来的完整请求体 - 解析JSON格式:用
json_decode($rawPayload, true)转成关联数组,解析前要加格式校验,遇到非法JSON请求直接记录日志返回错误响应,不要把脏数据存库 - 必做前置校验:存库之前必须按照支付渠道的规则校验请求签名,绝对不能无校验直接接收数据,否则很容易被恶意构造请求伪造支付状态
数据库存储的规范流程
- 提前设计好表结构,核心字段必须包含:
- 支付渠道返回的全局唯一交易号(加数据库唯一索引,专门用来应对Webhook重复推送的幂等处理)
- 关联本地业务的订单编号
- 支付金额、支付状态、交易币种等核心业务字段
- 原始JSON备份字段(建议用JSON类型或者TEXT类型,完整存下接收到的原始请求内容,后续排查问题不用翻服务日志)
- 用数据库事务包裹存储逻辑,保证支付记录和本地订单状态更新的一致性,示例代码:
// 先做幂等判断:重复收到同笔交易的通知直接放行返回成功 $transactionId = data_get($paymentData, 'trade_no'); if (PaymentRecord::where('transaction_id', $transactionId)->exists()) { return response('success', 200); } DB::transaction(function () use ($paymentData, $rawPayload) { // 写入完整支付记录 PaymentRecord::create([ 'transaction_id' => data_get($paymentData, 'trade_no'), 'order_no' => data_get($paymentData, 'out_trade_no'), 'amount' => data_get($paymentData, 'total_amount'), 'pay_status' => data_get($paymentData, 'trade_status'), 'raw_content' => $rawPayload ]); // 同步更新本地订单状态 Order::where('order_no', data_get($paymentData, 'out_trade_no')) ->update([ 'pay_status' => 'paid', 'paid_at' => now() ]); }); - 取值时统一用Laravel提供的
data_get()辅助函数做空值兼容,避免因为不同通知类型的字段差异触发未定义索引的报错
收尾响应要求
- 处理完存储逻辑后,必须按对应支付渠道的要求返回固定格式的响应(比如支付宝要求返回纯文本
success),否则渠道会判定通知失败持续重试 - 所有异常要捕获后写入日志,不要抛出未处理的500错误,避免触发渠道的无限重试机制
内容的提问来源于stack exchange,提问作者Haj Md Nexevo
相关产品推荐
相关产品推荐

