README

Zoom 可以通过 Webhooks 通知您的应用程序各种事件。此包可以帮助您处理这些 Webhooks。开箱即用，它会验证传入请求的 Zoom Webhook 签名。所有有效的调用都将记录到数据库中。您可以轻松定义当特定事件触发您的应用程序时应分发的作业或事件。

此包不会处理 Webhook 请求验证后应执行的操作。您仍需自行编写任何工作（例如，应发生什么）的代码。有关更多信息，请继续阅读。

在使用此包之前，我们强烈建议您阅读Zoom 上有关 Webhooks 的完整文档。

此包是基于绝对出色的 spatie/laravel-stripe-webhooks 进行修改的。

安装

您可以通过 composer 安装此包

composer require binary-cats/laravel-zoom-webhooks

服务提供程序将自动注册自己。

您必须使用以下命令发布配置文件

php artisan vendor:publish --provider="BinaryCats\ZoomWebhooks\ZoomWebhooksServiceProvider" --tag="config"

这是将要发布到 config/zoom-webhooks.php 的配置文件内容

return [

    /*
     * Zoom will sign each webhook using a verification token. You can find the secret used
     * in the  page of your Marketplace app: .
     */
    'signing_secret' => env('ZOOM_WEBHOOK_SECRET'),

    /*
     * You can define the job that should be run when a certain webhook hits your application
     * here. The key is the name of the Zoom event type with the `.` replaced by a `_`.
     *
     * You can find a list of Zoom webhook types here:
     * https://marketplace.zoom.us/docs/api-reference/webhook-reference#events.
     */
    'jobs' => [
        // 'meeting_started' => \BinaryCats\ZoomWebhooks\Jobs\HandleMeetingStarted::class,
    ],

    /*
     * The classname of the model to be used. The class should equal or extend
     * Spatie\WebhookClient\Models\WebhookCall
     */
    'model' => \Spatie\WebhookClient\Models\WebhookCall::class,

    /*
     * The classname of the model to be used. The class should equal or extend
     * BinaryCats\ZoomWebhooks\ProcessZoomWebhookJob
     */
    'process_webhook_job' => \BinaryCats\ZoomWebhooks\ProcessZoomWebhookJob::class,
];

在配置文件的 signing_secret 键中，您应添加一个有效的 Webhook 秘密。您可以在 HTTP Webhook 签名密钥中找到使用的秘密。

如果您已经安装了 Spatie\WebhookClient，则可以跳过迁移

接下来，您必须使用以下命令发布迁移

php artisan vendor:publish --provider="Spatie\WebhookClient\WebhookClientServiceProvider" --tag="migrations"

迁移发布后，您可以通过运行迁移来创建 webhook_calls 表

php artisan migrate

路由

最后，注意路由：在 Markerplace 控制台，您必须配置 Zoom Webhooks 应击中的 URL。在您的应用程序的路由文件中，您必须将该路由传递给 Route::zoomWebhooks()

我个人喜欢按域名分组功能，因此我建议使用 webhooks/zoom（特别是如果您计划有更多 Webhooks），但这是您的应用程序，由您决定。

# routes\web.php
Route::zoomWebhooks('webhooks/zoom');

幕后，这将注册一个由本包提供的控制器提供的 POST 路由。由于 Zoom 没有获取 csrf-token 的方法，您必须将该路由添加到 VerifyCsrfToken 中间件的 except 数组中

protected $except = [
    'webhooks/zoom',
];

替代中间件配置

当您有多个针对各种服务的 Webhooks，这些 Webhooks 由类似 Stripe Webhooks 和 Mailgun Webhooks 的包定义时，定义 VerifyCsrfToken 中间件可能更容易，如下所示：

protected $except = [
    'webhooks/*',
];

用法

Zoom 将为几种事件类型发送 Webhooks。您可以在 Zoom 文档中找到事件类型的完整列表。

Zoom 将为击中您的应用程序 Webhook URL 的所有请求签名。此包将自动验证签名是否有效。如果不有效，则请求可能不是由 Zoom 发送的。

除非出现严重错误，此包将始终对webhook请求响应200。发送200将防止Zoom反复重发相同的事件。所有带有有效签名的webhook请求都将记录在webhook_calls表中。该表有一个payload列，用于保存传入webhook的全部有效载荷。

如果签名无效，则请求不会记录在webhook_calls表中，但会抛出BinaryCats\ZoomWebhooks\Exceptions\WebhookFailed异常。如果在webhook请求过程中出现问题，抛出的异常将保存在exception列中。在这种情况下，控制器将发送500而不是200。

此包提供了两种处理webhook请求的方式：您可以选择排队一个作业或监听包将引发的的事件。

使用作业处理webhook请求

如果您希望在特定事件类型传入时执行某些操作，可以定义一个执行工作的作业。以下是一个此类作业的示例

<?php

namespace App\Jobs\ZoomWebhooks;

use Illuminate\Bus\Queueable;
use Illuminate\Queue\SerializesModels;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;
use Spatie\WebhookClient\Models\WebhookCall;

class HandleMeetingStarted implements ShouldQueue
{
    use InteractsWithQueue, Queueable, SerializesModels;

    /** @var \Spatie\WebhookClient\Models\WebhookCall */
    public $webhookCall;

    public function __construct(WebhookCall $webhookCall)
    {
        $this->webhookCall = $webhookCall;
    }

    public function handle()
    {
        // do your work here

        // you can access the payload of the webhook call with `$this->webhookCall->payload`
    }
}

Spatie强烈建议您使此作业可排队，以最大限度地减少webhook请求的响应时间。异步处理还允许您处理更多的Zoom webhook请求并避免超时。更多关于队列的信息。

验证令牌位于authorization请求头中。

创建您的作业后，您必须在zoom-webhooks.php配置文件中的jobs数组中注册它。键应该是zoom事件类型的名称，但用.替换为_。值应该是完全限定的类名。

// config/zoom-webhooks.php

'jobs' => [
    'meeting_started' => \App\Jobs\ZoomWebhooks\HandleMeetingStarted::class,
],

使用事件处理webhook请求

您可以选择监听此包将引发的事件，而不是在webhook请求传入时排队作业以执行某些操作。每当有效的请求击中您的应用程序时，此包将触发一个zoom-webhooks::<event-name>事件。

事件的有效载荷将是为传入请求创建的WebhookCall实例。

让我们看看您如何监听此类事件。您可以在EventServiceProvider中注册事件监听器。

/**
 * The event listener mappings for the application.
 *
 * @var array
 */
protected $listen = [
    'zoom-webhooks::meeting.started' => [
        App\Listeners\Zoom\MeetingStarted::class,
    ],
];

以下是一个此类监听器的示例

<?php

namespace App\Listeners\Zoom;

use Illuminate\Contracts\Queue\ShouldQueue;
use Spatie\WebhookClient\Models\WebhookCall;

class MeetingStarted implements ShouldQueue
{
    public function handle(WebhookCall $webhookCall)
    {
        // do your work here

        // you can access the payload of the webhook call with `$webhookCall->payload`
    }
}

Spatie强烈建议您使事件监听器可排队，这将最大限度地减少webhook请求的响应时间，并允许您消费更多的Zoom webhook请求，同时避免超时。

上述示例只是Laravel中处理事件的一种方法。要了解其他选项，请阅读Laravel处理事件文档。

高级用法

重试处理webhook

所有传入的webhook请求都写入数据库。当处理webhook调用时出现问题时，这非常有价值。您可以在调查并修复失败原因后，轻松地重试处理webhook调用，如下所示

use Spatie\WebhookClient\Models\WebhookCall;
use BinaryCats\ZoomWebhooks\ProcessZoomWebhookJob;

dispatch(new ProcessZoomWebhookJob(WebhookCall::find($id)));

执行自定义逻辑

您可以使用自己的作业类添加一些应该在排队的作业之前和/或之后执行的自定义逻辑。您可以通过在zoom-webhooks配置文件的process_webhook_job键中指定自己的作业类来实现这一点。该类应扩展BinaryCats\ZoomWebhooks\ProcessZoomWebhookJob。

以下是一个示例

use BinaryCats\ZoomWebhooks\ProcessZoomWebhookJob;

class MyCustomZoomWebhookJob extends ProcessZoomWebhookJob
{
    public function handle()
    {
        // do some custom stuff beforehand

        parent::handle();

        // do some custom stuff afterwards
    }
}

处理多个签名密钥

有时您可能希望该包处理多个端点和密钥。以下是如何配置此行为的说明。

如果您正在使用Route::zoomWebhooks宏，可以按以下方式附加configKey

Route::zoomWebhooks('webhooks/zoom/{configKey}');

或者，如果您正在手动定义路由，可以按以下方式添加configKey

Route::post('webhooks/zoom/{configKey}', 'BinaryCats\ZoomWebhooks\ZoomWebhooksController');

如果存在此路由参数，验证中间件将使用不同的配置键来查找密钥，通过将给定的参数值附加到默认配置键。例如，如果Zoom发送到webhooks/zoom/my-special-secret，则需要添加一个名为signing_secret_my-special-secret的新配置，如下所示

// secret for when Zoom posts to webhooks/zoom/account
'signing_secret_account' => 'whsec_abcdef',
// secret for when Zoom posts to webhooks/zoom/my-special-secret
'signing_secret_my-special-secret' => 'whsec_123456',

关于Zoom

Zoom Zoom是一个基于Web的视频会议工具，具有本地桌面客户端和移动应用，用户可以在线进行会议，是否使用视频均可。

变更日志

请参阅CHANGELOG以获取有关最近更改的更多信息。

测试

composer test

贡献

请参阅CONTRIBUTING以获取详细信息。

安全

如果您发现任何与安全相关的问题，请通过电子邮件cyrill.kalita@gmail.com联系，而不是使用问题跟踪器。

明信片软件

您可以使用此软件包，但如果它进入了您的生产环境，我们非常感谢您从您家乡给我们寄一张明信片，并注明您正在使用我们的哪些软件包。

鸣谢

向Spatie致以崇高的敬意，他们的工作给了我们巨大的灵感。

支持我们

Binary Cats是一家位于美国伊利诺伊州的网络机构。

许可证

MIT许可证（MIT）。请参阅许可证文件以获取更多信息。

abdallamohammed / laravel-zoom-webhooks

维护者

详细信息