PHP怎么使用Webhook接收器_PHP第三方服务回调处理【指南】-php教程-PHP中文网

合法webhook请求需通过平台签名验证：github用hmac-sha256比对x-hub-signature-256，stripe用signature类验签，微信支付v3需私钥验authorization头；php须一次性读取php://input原始体用于验签与解析，避免重复读取失败。

php怎么使用webhook接收器_php第三方服务回调处理【指南】

第三方服务发来的 Webhook 不是“谁都能发”，但 PHP 本身不会自动验签或校验来源，直接 $_POST 或 file_get_contents('php://input') 拿到数据就处理，等于裸奔。

绝大多数平台（如 GitHub、Stripe、微信支付）会在请求头里带签名，比如 X-Hub-Signature-256、Stripe-Signature、Authorization，你得用他们文档给的密钥和算法重新算一遍，比对一致才可信。

别只检查 $_SERVER['HTTP_USER_AGENT'] 或 IP 白名单——这些都容易伪造
GitHub 用 hash_hmac('sha256', $payload, $secret)，结果前缀加 sha256= 再跟 header 值比对
Stripe 要用 Stripe\Signature 类的 verifyHeader 方法，传入原始 body（不能经 json_decode 或 parse_str 处理过）
微信支付 v3 的回调用 Authorization 头里的签名 + 时间戳 + 随机串，需用私钥验签，不是简单 HMAC

很多 Webhook 发的是 application/json，但 PHP 默认不把 JSON 自动塞进 $_POST。直接 $_POST 是空的，而 file_get_contents('php://input') 是唯一可靠入口——但它只能读一次，且内容是原始字节流。

常见错误是：先 json_decode(file_get_contents('php://input'))，再想二次读取做验签，结果第二次读就是空字符串。

必须在开头一次性读完并存到变量，比如 $raw = file_get_contents('php://input');
验签用 $raw，解析也用 $raw：$data = json_decode($raw, true);
如果平台要求验证 Content-Type，检查 $_SERVER['CONTENT_TYPE'] === 'application/json'，但别依赖它做安全控制
注意 php://input 在 enctype="multipart/form-data" 时不可用，不过 Webhook 几乎不用这种编码

第三方服务发 Webhook 时，通常会等你的 HTTP 响应（比如 200 OK），超时时间普遍很短（3~10 秒）。如果你在响应前查数据库、调外部 API、生成 PDF，很容易超时导致重试甚至丢事件。

PHP 8.5.5

PHP 8.5.5 是 PHP 8.5 分支的维护更新版本。该版本延续了“小步快跑”的迭代逻辑，通过深度错误修复、底层性能微调以及安全加固，旨在为开发者提供一个更健壮、更高效的运行环境。该版本严格遵守语义化版本规范，不包含破坏性变更。

下载

这不是性能优化问题，是契约问题：对方认为“你收到了”，不代表“你处理完了”。

收到后立刻返回 200（哪怕只写 http_response_code(200); exit;），再异步处理
把 $raw 和关键字段（如 event_type、id）写进数据库或 Redis，交给队列（如 Beanstalkd、Redis List、甚至简单 cron 扫描）消费
别在 Webhook 入口里用 sleep()、shell_exec('curl ...') 或同步 Guzzle 请求
记录原始 $raw 到文件或 DB，方便出问题时回放——别只记 $data，因为验签失败时你可能根本没拿到结构化数据

网络不稳定、对方重试机制、甚至你自己测试点多了，都会造成同一事件多次到达。这不是异常，是分布式系统的常态。靠“不重发”不现实，得靠“幂等处理”。

核心思路：用事件自带的唯一标识（比如 id、delivery_id、x-github-delivery）做去重锚点。

收到后先查 DB 或 Redis 是否已存在该 id，有则直接返回 200，不重复处理
Redis 示例：if (redis->set("webhook:gh:$delivery_id", 1, ['NX', 'EX' => 3600])) { /* 处理 */ } else { /* 已处理过 */ }
数据库建议建唯一索引：ALTER TABLE webhook_logs ADD UNIQUE KEY uniq_delivery (provider, delivery_id);，插入失败即跳过
注意：别用时间戳或自增 ID 做幂等键，它们不跨服务唯一；也别用整个 payload 做 key，太长且易变

Webhook 的难点不在“接到”，而在“接得稳、验得准、跑得异步、扛得住重放”。最常被忽略的是：原始 body 只能读一次，验签和解析必须共享同一份字节流——这点卡住过太多人。