EasyPost 中监听运费退款成功的正确 Webhook 事件类型-java教程-PHP中文网

EasyPost 并不通过 return_update 状态通知运费退款完成，而是专门触发 refund.successful 类型的 Webhook 事件；该事件在 carrier（如 USPS）实际完成退款后异步发出，通常延迟数日甚至数周，且无法在测试环境中模拟。

easypost 并不通过 `return_update` 状态通知运费退款完成，而是专门触发 `refund.successful` 类型的 webhook 事件；该事件在 carrier（如 usps）实际完成退款后异步发出，通常延迟数日甚至数周，且无法在测试环境中模拟。

在 EasyPost 的事件体系中，refund.successful 是唯一用于标识运费退款已被承运商正式接受并完成结算的 Webhook 事件类型。这与常见的物流状态更新（如 status_update、out_for_delivery）有本质区别：它不反映包裹轨迹，而是代表财务动作的最终确认。

✅ 正确监听方式

你需要在 Webhook 接收端显式检查 event.type 字段（而非 result.statusDetail），示例如下：

Temu欧洲站-退货退款

Temu 欧洲站电商退货退款API，通过 LinkFox 网关转发 Partner EU Returns & Refunds / 售后退货退款相关后台/Temu 接口（退货申请、退款、售后单查询与处理等），接口将按 Partner 文档逐条接入。当用户提到 Temu EU 退货、退款、售后退货、return...

下载

// 假设 result 是解析后的 JSON Webhook payload（顶层对象）
String eventType = (String) result.get("event_type"); // 注意：EasyPost v3+ 使用 event_type 字段

if ("refund.successful".equals(eventType)) {
    Map<string object> eventData = (Map<string object>) result.get("data");
    Map<string object> refundData = (Map<string object>) eventData.get("object");

    String refundId = (String) refundData.get("id");
    String shipmentId = (String) refundData.get("shipment_id");
    BigDecimal amount = new BigDecimal((String) refundData.get("amount"));
    String carrier = (String) refundData.get("carrier");
    String status = (String) refundData.get("status"); // 通常为 "submitted" 或 "succeeded"

    // 关联本地订单并执行退款逻辑
    Shipment userShipment = shipmentService.retrieveShipmentFromEasypostId(shipmentId);
    if (userShipment != null && "succeeded".equals(status)) {
        try {
            Refund stripeRefund = stripeService.refund(userShipment.getStripeChargeId(), amount.doubleValue());
            userShipment.setStripeRefundId(stripeRefund.getId());
            userShipment.setStatus(ShipmentStatus.REFUND_PROCESSED);
            userShipment.setEasypostStatus(EasypostShipmentStatus.REFUNDED);
            shipmentService.updateShipment(userShipment);

            activityLoggerService.insert(
                userShipment.getUser(),
                userShipment,
                activityLoggerService.getShipmentRefundProcessed(userShipment, amount.doubleValue()),
                ActivityMessageType.REFUND_PROCESSED
            );
        } catch (StripeException e) {
            log.error("Failed to issue Stripe refund for EasyPost refund {}", refundId, e);
        }
    }
}</string></string></string></string>

⚠️ 关键注意事项

statusDetail 字段不适用于退款事件：你当前代码中依赖 statusDetail.equals("return_update") 是无效的——EasyPost 的 return_update 仅用于退货包裹轨迹（如 return_received），与运费退款无关。
事件延迟不可忽略：USPS 退款平均需 15–30 天才触发 refund.successful；FedEx/UPS 通常更快（1–7 天），但均属异步行为，绝不可依赖“提交退款请求”即视为成功。
测试环境限制：EasyPost 的 test 模式不会生成真实的 refund.successful Webhook，即使调用 Refund.create(...) 测试方法。生产环境验证前，建议使用 live key + 小额真实标签进行端到端测试。
幂等性必须保障：因网络重试或事件重复投递，同一 refund.successful 事件可能多次到达，请基于 refund.id 做去重处理（如数据库唯一索引或 Redis Set 记录已处理 ID）。