WooCommerce webhook怎么配置？

学完这篇，你能在 WooCommerce 后台从零配好一个能真正收到数据的 webhook，并知道怎么验证签名、怎么排查收不到的问题。

第一步：确认版本和访问前提

WooCommerce 的 webhook 是内置功能（2.2 版本就有），不需要装插件。入口固定在：WordPress 后台 → WooCommerce → 设置 → 高级 → Webhook。

开始前确认两件事：一是你的站点能被公网访问，本地 localhost 建站对方是收不到的；二是接收方地址最好是 HTTPS。

注意：如果你的站点在 Cloudflare、宝塔或企业防火墙后面，先确认外部的 POST 请求不会被拦截，否则后面会在「为什么收不到」上白耗一小时。

第二步：先准备一个测试接收地址

打开 webhook.site，它会给你一个临时 URL，比如 https://webhook.site/xxxxxxxx-xxxx。这个页面能实时显示收到的请求头和请求体，用来验证配置是否通。

第三步：新建 webhook

在 WooCommerce → 设置 → 高级 → Webhook 页面，点顶部的「添加 webhook」按钮，会展开一个表单，填这些字段：

• 名称：自己看得懂就行，例如「订单创建-推给ERP」
• 状态：选「启用」
• 主题：下拉里每个资源（订单、产品、优惠券、客户）都有「创建/更新/删除/恢复」四个动作，做订单同步就选「订单创建」
• 交付 URL：粘贴第二步的测试地址
• 密钥：点右侧「生成」，或自己填一串随机字符串，记下来
• API 版本：选「WP REST API Integration v3」（推荐），Legacy v3 是旧格式

填完点「保存 webhook」。

注意：主题选定后无法修改，选错了只能删除重建；密钥保存后就不再明文显示，务必先存到自己的密码管理器里。

第四步：触发一次并看交付日志

前台或后台新建一个订单并把它变成「处理中」，就触发了「订单创建」。然后回到这个 webhook 的编辑页，往下拉有「Webhook 交付日志」（Delivery Logs），会列出每次请求的时间、状态码和响应体。状态码 200 说明对方收到了。也可以去 WooCommerce → 状态 → 日志，选 webhooks-delivery 这个日志源看详情。

注意：WooCommerce 是通过 Action Scheduler 异步发送的，不是下单瞬间就到，通常几秒内。如果日志里一直是「挂起」，检查 wp-config.php 里是否定义了 DISABLE_WP_CRON 却没配服务器的定时任务。

第五步：验证签名

别人可以伪造请求打你的接口，所以必须校验签名。每个请求都带 X-WC-Webhook-Signature 头，值是 HMAC-SHA256 后 Base64。PHP 里这样验：

$payload = file_get_contents('php://input');
$sig = base64_encode(hash_hmac('sha256', $payload, $secret, true));
$incoming = $_SERVER['HTTP_X_WC_WEBHOOK_SIGNATURE'] ?? '';
if (!hash_equals($sig, $incoming)) {
    http_response_code(401);
    exit;
}

请求体是 JSON，其他有用的头还有 X-WC-Webhook-Topic、X-WC-Webhook-Resource、X-WC-Webhook-Delivery-ID。

注意：hash_hmac 第四个参数必须传 true 输出二进制再 Base64。少传这个参数会得到十六进制字符串的 Base64，跟 WooCommerce 算出来的永远对不上，这是最常见的坑。

第六步：接口收了 200 但拿不到数据？

多半是用了 $_POST 去读。WooCommerce 发的是 application/json，必须用 php://input 读原始流，$_POST 在这种情况下是空的。

另外，Action Scheduler 在超时或失败后可能重投，接口要按 X-WC-Webhook-Delivery-ID 做幂等，避免重复建单。

小结

• 入口：WooCommerce → 设置 → 高级 → Webhook，点「添加 webhook」
• 主题选错不能改，只能删掉重建；密钥保存后不再明文显示
• 发送是异步的，靠 Action Scheduler，不是实时；WP-Cron 被禁用会导致一直挂起
• 签名 = Base64(HMAC-SHA256(payload, secret)，二进制输出)，用 hash_equals 比较
• 取数据用 php://input，不是 $_POST
• 排错第一站是编辑页底部的「Webhook 交付日志」