PHP对接Stripe API时webhook代码各片段功能逐步骤解释问询

第一段代码：获取Stripe请求原始载荷 #

$payload = @file_get_contents('php://input');

• 作用是读取Stripe发送到你webhook地址的POST请求原始内容：Stripe触发事件后会向你配置的webhook地址发送JSON格式的事件数据，php://input是PHP提供的读取原始HTTP请求体的专用流，@符用于抑制非预期的读取报错，拿到的原始内容会存入$payload变量供后续解析。

第二段代码：解析生成Stripe事件对象 #

$event = null;
try {
    $event = \Stripe\Event::constructFrom(
        json_decode($payload, true)
    );
} catch (\UnexpectedValueException $e) {
    // 无效载荷
    echo '⚠️  解析基础请求时发生Webhook错误';
    http_response_code(400);
    exit();
}

• $event是Stripe官方SDK封装的事件对象，包含当前触发事件的所有元数据和关联业务信息
• 传入$payload的原因：需要先把原始JSON字符串解码为数组，再用constructFrom方法转为SDK内置的Event类实例，后续可以直接用对象属性读取值，不需要手动解析嵌套数组
• 异常捕获逻辑是为了拦截非法请求：如果有人恶意向你的webhook地址发送无效格式的请求，解析失败就直接返回400错误并终止执行，避免后续逻辑出错

第三段代码：按事件类型处理业务逻辑 #

// 处理事件
switch ($event->type) {
    case 'customer.subscription.trial_will_end':
        $subscription = $event->data->object; // 包含一个\Stripe\Subscription对象
        // 后续可定义并调用方法处理试用即将到期事件
        // handleTrialWillEnd($subscription);
        break;
    // 其他事件case省略
    default:
        // 未预期的事件类型
        echo '收到未知事件类型';
}

• Stripe的Event对象有固定结构：$event->data->object固定存放当前事件对应的业务资源实例
• 你示例中都是订阅相关事件，所以$event->data->object就是完整的\Stripe\Subscription订阅对象，包含订阅ID、所属客户ID、订阅状态、到期时间、关联的产品/价格ID、试用结束时间等所有订阅相关属性，你可以直接读取$subscription->id、$subscription->status等属性做后续业务处理
• switch的作用就是匹配你需要处理的事件类型，不需要处理的事件直接走default逻辑跳过即可

第四段代码：返回成功响应 #

http_response_code(200);

• 这是Stripe webhook的强制要求：你收到事件并处理完成后必须返回200状态码，告知Stripe你已成功接收并处理该事件
• 如果你返回非200的状态码（比如404、500等），Stripe会判定你未收到事件，会按照官方的重试规则重复推送该事件，最长会重试3天，所以必须返回200避免重复触发业务逻辑

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