Laravel中Postgrid Webhook未被调用（报419/405错误）求助排查

一、先处理405（方法不允许）错误 #

• 核对Postgrid Webhook配置的请求方法与Laravel路由是否匹配：Postgrid默认用POST触发Webhook，确保你的路由定义为Route::post('/webhook/postgrid', [YourController::class, 'handlePostgridWebhook'])，若路由用了GET或其他方法会直接返回405。
• 排查路由冲突：检查是否有其他路由规则优先匹配了该Webhook URL，导致请求被导向不支持POST的处理逻辑。

二、解决419（CSRF令牌验证失败）错误 #

Laravel默认对所有POST请求做CSRF校验，第三方Webhook无法携带你的站点CSRF令牌，必须将Webhook路径加入白名单：

• 打开app/Http/Middleware/VerifyCsrfToken.php，在$except数组中添加Webhook完整路径：

protected $except = [
    '/webhook/postgrid',
    // 若用了api前缀则写 '/api/webhook/postgrid'
];

• 确保路径与Postgrid配置的URL完全一致，包括前缀、大小写（Laravel路由默认不区分大小写，但严格匹配更稳妥）。

三、为什么Laravel日志无请求记录？ #

• 405/419错误属于中间件拦截级别的错误，请求未到达控制器逻辑，所以不会在业务日志中记录。先解决上述两个错误，再观察日志是否出现请求痕迹。
• 检查服务器（Nginx/Apache）的访问日志：如果服务器日志也没有该请求记录，说明Postgrid的Webhook请求根本没到达你的服务器——可能是URL拼写错误、站点强制HTTPS但Postgrid用了HTTP、网络链路不通，或是Postgrid侧存在防火墙拦截。
• 确认Postgrid的Webhook URL配置：检查是否遗漏了端口（非80/443端口需手动添加）、域名是否正确，以及是否存在路径拼写错误。

四、额外验证步骤 #

• 用curl或Postman手动模拟Posthook请求，测试你的Webhook端点：

curl -X POST https://your-domain.com/webhook/postgrid \
  -H "Content-Type: application/json" \
  -d '{"event": "postcard.created", "data": {"id": "test_123"}}'

如果手动请求仍报错，问题出在Laravel配置；如果手动请求正常，则需联系Postgrid排查他们的请求发送逻辑（比如请求头异常、签名验证规则冲突等）。

• 检查Laravel的storage/logs目录下的最新日志，419错误通常会被记录在框架日志中，可能你之前没注意到。
• 若使用Cloudflare等CDN，排查WAF规则是否将Postgrid的请求判定为恶意请求拦截。

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