如何在Laravel中为Zoho Sign创建GET请求的Webhook接收器

我正在把Zoho Sign集成到Laravel应用里，需要搭建一个Webhook接收器来获取Zoho Sign的已完成文档，但Zoho Sign的Webhook只支持GET请求。我之前已经成功实现过POST请求的Webhook接收器，但不清楚怎么处理GET请求的Webhook端点，能不能给我指导或代码示例，说明如何在Laravel中创建监听Zoho Sign GET请求的Webhook接收器？我需要捕获Zoho Sign发送的Webhook数据并在Laravel内处理。

我已经尝试了以下操作：

1. 在web_api.php中创建路由：

Route::get('receive-waiver', [WaiverController::class, 'ReceiveWaiver']);

2. 创建了Waiver控制器及ReceiveWaiver方法：

<?php

namespace App\Http\Controllers\Zoho;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;

class WaiverController extends Controller
{

    public function ReceiveWaiver(Request $request)
    {
        \Log::info('Webhook success!');
        \Log::info('Webhook Data: ' . json_encode($request['requests']));
        \Log::info('Webhook Document: ' . json_encode($request['requests']['document_ids']));
        try {

            if (!empty($request['requests'])) {
                $waiverData = json_encode($request['requests']);
                $waiverDocument = json_encode($request['requests']['document_ids']);
                \Log::info('Success Webhook Data: ' . $waiverData);
                \Log::info('Success Webhook Document: ' . $waiverDocument);

            }

            return response()->json(['message' => 'Webhook received'], true);
        } catch (\Exception $e) {
            $errorMessage = $e->getMessage();
            \Log::info('Error Webhooks: ' . $errorMessage);
            return response()->json(['message' => $e->getMessage()]);
        }
    }
}

Zoho Sign的Webhook设置截图如下：

1. 路由配置确认 #

你的路由设置逻辑正确，但需注意Laravel路由分组的差异：

• 若Webhook是对外暴露的接口，建议放在api.php中（默认无CSRF验证），避免被框架的CSRF拦截机制阻断请求
• 如果必须放在web.php中，需要将该路由加入CSRF白名单：
  在App\Http\Middleware\VerifyCsrfToken类中修改：

  protected $except = [
      'receive-waiver',
  ];
  

2. 修正控制器参数获取逻辑 #

GET请求的参数通过URL Query传递，Zoho Sign的Webhook数据会以查询参数形式发送，不能用POST请求的方式直接访问$request['requests']，需改用$request->query()或$request->input()方法获取参数。

修正后的控制器代码：

<?php

namespace App\Http\Controllers\Zoho;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Log;

class WaiverController extends Controller
{
    public function ReceiveWaiver(Request $request)
    {
        Log::info('Webhook 请求已接收，原始参数: ', $request->query());

        try {
            // 获取Zoho Sign发送的核心参数
            $requestsData = $request->query('requests');
            $documentIds = $request->query('document_ids');

            // 解析JSON格式的requests参数（Zoho Sign可能会将结构化数据转成JSON字符串传递）
            if ($requestsData) {
                $decodedRequests = json_decode($requestsData, true);
                if (json_last_error() === JSON_ERROR_NONE) {
                    Log::info('解析后的Requests数据: ', $decodedRequests);
                } else {
                    Log::warning('Requests参数解析失败: ' . $requestsData);
                }
            }

            // 处理文档ID列表（可能是以逗号分隔的字符串）
            if ($documentIds) {
                $docIdList = explode(',', $documentIds);
                Log::info('文档ID列表: ', $docIdList);
                
                // 这里可添加业务逻辑：比如调用Zoho Sign API拉取完整文档信息
                // foreach($docIdList as $id) {
                //     $document = Http::withToken(config('services.zohosign.api_token'))
                //         ->get("https://sign.zoho.com/api/v1/documents/{$id}");
                // }
            }

            return response()->json(['message' => 'Webhook已接收'], 200);
        } catch (\Exception $e) {
            Log::error('Webhook处理失败: ' . $e->getMessage());
            return response()->json(['message' => '处理失败'], 500);
        }
    }
}

3. 添加Webhook来源验证（安全必备） #

为防止恶意请求，需验证请求确实来自Zoho Sign：

1. 在Zoho Sign的Webhook设置中配置一个自定义密钥（比如webhook_secret）
2. 收到请求时验证该密钥是否匹配本地配置

示例验证逻辑（添加到控制器方法开头）：

$configuredSecret = config('services.zohosign.webhook_secret');
$receivedSecret = $request->query('secret');

if (!$receivedSecret || $receivedSecret !== $configuredSecret) {
    Log::warning('无效的Webhook请求，签名不匹配');
    return response()->json(['message' => '无效请求'], 403);
}

4. 测试Webhook #

用curl模拟Zoho Sign的GET请求，验证接口是否正常工作：

curl "http://你的应用域名/receive-waiver?requests=%7B%22status%22%3A%22completed%22%7D&document_ids=doc_123,doc_456&secret=你的自定义密钥"

之后查看Laravel日志文件（storage/logs/laravel.log），确认参数是否被正确接收和解析。

内容的提问来源于stack exchange，提问作者Rommel Verterra Traya