Laravel Cashier for Paddle Webhook相关技术问题咨询

1. 监听指定的Paddle Webhook事件 #

要监听Transaction Completed、Subscription Created等事件，你需要通过Laravel Cashier的ReceivedWebhook事件统一捕获，再根据事件类型做针对性处理：

1. 注册监听器
   在app/Providers/EventServiceProvider.php的$listen数组中添加绑定：

   protected $listen = [
       \Laravel\Paddle\Events\ReceivedWebhook::class => [
           \App\Listeners\HandlePaddleWebhook::class,
       ],
   ];
   

   运行php artisan event:generate生成监听器文件。

2. 在监听器中判断事件类型
   在生成的HandlePaddleWebhook.php中，通过$event->payload['event_type']匹配对应的Paddle事件：

   public function handle(ReceivedWebhook $event)
   {
       $payload = $event->payload;
       switch ($payload['event_type']) {
           case 'transaction.completed':
               // 处理交易完成逻辑
               break;
           case 'subscription.created':
               // 处理订阅创建逻辑
               break;
           case 'subscription.updated':
               // 处理订阅更新逻辑
               break;
           case 'subscription.canceled':
               // 处理订阅取消逻辑
               break;
           default:
               // 忽略未处理的事件类型
               return;
       }
   }
   

   注：Paddle的事件类型为小写+点分隔格式，与你提到的显示名称一一对应。

2. 结账会话传入自定义数据并在Webhook中获取 #

可以通过withMetadata()方法传入自定义数据，示例代码如下：

$checkout = $user->checkout([$plan_id])
    ->returnTo(route("home"))
    ->withMetadata([
        'user_id' => $user->id,
        'custom_order_sn' => 'ORD-20240501-001'
    ]);

当Paddle触发Webhook时，自定义数据会包含在payload的metadata字段中，可在监听器中直接获取：

$customData = $event->payload['metadata'];
$userId = $customData['user_id'];
$orderSn = $customData['custom_order_sn'];

3. Paddle多次发送Webhook请求的原因 #

这不属于异常情况，是Paddle的重试机制导致的：

• 当你的Webhook端点返回非2xx状态码（如500、超时、404）时，Paddle会自动重试，重试间隔会逐渐拉长。
• 使用Ngrok时，若本地服务中断、Ngrok隧道不稳定（如网络波动、本地重启服务），会导致Paddle无法收到正常的200响应，从而触发重试。

解决建议：

• 本地调试时保持Laravel服务和Ngrok隧道持续运行。
• 确保Webhook端点逻辑稳定，避免抛出异常或超时，处理完成后返回200响应（Cashier默认会自动处理响应，但自定义逻辑抛出异常会导致返回500）。

内容的提问来源于stack exchange，提问作者Efon godstime