本地Laravel项目用ngrok对接WhatsApp Webhook失败求助

1. 核对URL与验证token的一致性 #

• 确认Meta平台填写的Callback URL是ngrok生成的完整HTTPS链接，需包含完整路由路径（例如https://xxxx-xx-xx-xx-xx.ngrok.io/webhook/whatsapp），不能遗漏路由后缀。
• 验证token要与Laravel控制器中定义的完全匹配，注意大小写、空格等细节，避免复制粘贴错误。

2. 排除Laravel CSRF拦截 #

Laravel默认的CSRF中间件可能影响请求处理，需将webhook路由加入CSRF白名单：
在app/Http/Middleware/VerifyCsrfToken.php的$except数组中添加路由：

protected $except = [
    '/webhook/whatsapp',
];

3. 确认ngrok端口映射正确 #

• 若本地Laravel服务用php artisan serve运行在8000端口，需执行ngrok http 8000确保端口映射一致；使用Valet/Homestead的话，要对应映射80/443端口。
• 避免端口冲突，确保本地服务器和ngrok没有占用同一端口。

4. 检查验证逻辑正确性 #

WhatsApp验证要求接收GET请求后，校验hub_mode、hub_verify_token参数，匹配则返回hub_challenge值。检查控制器代码是否符合逻辑：

public function verify(Request $request)
{
    $verifyToken = env('WHATSAPP_VERIFY_TOKEN');

    if ($request->hub_mode === 'subscribe' && $request->hub_verify_token === $verifyToken) {
        return response($request->hub_challenge, 200);
    }

    return response('Invalid token', 403);
}

可直接在浏览器访问ngrok验证URL并手动拼接参数（如https://xxxx.ngrok.io/webhook/whatsapp?hub_mode=subscribe&hub_challenge=12345&hub_verify_token=你的token），测试返回值是否符合预期。

5. 排查网络与防火墙限制 #

• 暂时关闭本地防火墙，排除拦截ngrok请求的可能。
• 若在公司/校园网络下，尝试切换到手机热点，避免代理或网络规则阻断请求。

6. 确保ngrok隧道稳定 #

• 免费版ngrok的URL会定期变更，若Meta平台填写的URL已过期，需重新生成隧道并更新Callback URL。
• 可通过ngrok http 8000 --region us指定地区，提升隧道连接稳定性；若连接异常，重启ngrok重试。

7. 通过Laravel日志定位问题 #

查看storage/logs/laravel.log，确认请求是否到达控制器、是否存在参数解析错误或token匹配失败等日志，快速定位问题节点。

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