PHP框架中拼接Webhook数据并实现事件监听，需先明确推送方数据结构、签名验证方式及事件类型映射，再构建可扩展接收与分发机制：定义无CSRF路由、用php://input获取原始负载、按HMAC或时间戳+nonce校验签名、依X-GitHub-Event等头提取事件类型、动态实例化事件类触发Laravel事件系统、监听器中合并上下文并提取关键字段后投递队列。
PHP框架中拼接Webhook推送数据并实现事件监听，需先明确推送方的数据结构、签名验证方式及事件类型映射关系，再在框架内构建可扩展的接收入口与事件分发机制。
定义Webhook接收路由与基础校验
在Laravel中，于routes/api.php添加无CSRF保护的POST路由：Route::post('/webhook/{provider}', [WebhookController::class, 'handle'])->withoutMiddleware(['csrf']);
这一步必须关闭CSRF中间件，否则第三方服务推送会因token缺失直接返回419错误。
在WebhookController中，第一步提取原始请求体：$payload = file_get_contents('php://input');——不能用$request->all()，因为Webhook常以application/json或application/x-www-form-urlencoded原始格式发送，all()会丢失嵌套结构或解析失败。
立即学习“PHP免费学习笔记（深入）”；
解析并验证Webhook签名
方法一：HMAC-SHA256校验（如GitHub、Stripe常用）
从请求头获取X-Hub-Signature-256，用预设密钥对$payload计算哈希：$expected = 'sha256=' . hash_hmac('sha256', $payload, config('services.webhook.secret'));
【密钥必须严格匹配推送平台后台配置的secret，且不能硬编码在控制器里】
方法二：时间戳+签名防重放（如企业微信）
检查timestamp参数是否在5分钟有效窗口内，再用sha256(sha256(timestamp + nonce) + secret)比对msg_signature字段。
按事件类型分发到对应监听器
第一步：从解析后的数组中提取事件标识字段，如GitHub用X-GitHub-Event头，Slack用event.type，企业微信用EventType。
第二步：构造事件类名，例如'App\Events\Webhook\' . Str::studly($event) . 'Event'，再通过event(new $eventClass($payload))触发Laravel事件系统。
第三步：在AppProvidersEventServiceProvider的$listen数组中注册监听器，如[PushEvent::class => [SendNotificationListener::class]]。
这一步要求事件类必须继承IlluminateFoundationEventsDispatchable，否则event()调用无效。
拼接结构化Webhook数据供业务使用
在具体监听器的handle()方法中，将原始$payload与上下文信息合并：
$data = array_merge(['received_at' => now()->toISOString(), 'provider' => $this->provider], $this->payload);
若需兼容多平台字段差异，用Arr::only()提取关键字段：Arr::only($data, ['id', 'action', 'repository.name', 'pull_request.number'])——注意点号路径需配合data_get()或自定义递归取值函数，原生Arr::only()不支持嵌套键。
最后将拼接结果写入队列：ProcessWebhookJob::dispatch($data)->onQueue('webhooks');，避免同步处理阻塞HTTP响应。
