README

BigBlueButton 可以通过 webhooks 通知您的应用程序邮件事件。此包可以帮助您处理这些 webhooks。默认情况下，它将验证所有传入请求的 BigBlueButton 签名。看起来签名验证目前并不简单，并且与文档不匹配。所有有效调用都将记录到数据库中。您可以轻松定义在特定事件触达您的应用程序时应分发的作业或事件。

此包不会处理验证 webhook 请求后应该执行的操作。您仍然需要自己编写任何工作（例如，关于付款）的代码。

在开始使用此包之前，我们强烈建议您阅读BigBlueButton 的完整 webhooks 文档。

此包是几乎逐行复制了绝对精彩的 spatie/laravel-stripe-webhooks

安装

您可以通过 composer 安装此包

composer require binary-cats/laravel-bigbluebutton-webhooks

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

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

php artisan vendor:publish --provider="BinaryCats\BigBlueButtonWebhooks\BigBlueButtonWebhooksServiceProvider" --tag="config"

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

return [

    /*
     * BigBlueButton will sign each webhook using a shared secret.
     */
    'signing_secret' => env('BBB_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 BigBlueButton event type with the `.` replaced by a `_`.
     * 
     * The package will automatically convert the keys to lowercase, but you should
     * be cognisant of the fact that array keys are case-sensitive
     */
    'jobs' => [
        'meeting-created' => \BinaryCats\BigBlueButtonWebhooks\Jobs\MeetingCreatedJob::class,
    ],

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

    /*
     * The classname of the model to be used. The class should equal or extend
     * Spatie\WebhookClient\ProcessWebhookJob
     */
    'process_webhook_job' => \BinaryCats\BigBlueButtonWebhooks\ProcessBigBlueButtonWebhookJob::class,
];

在配置文件的 signing_secret 键中，您应该添加 BigBlueButton 服务器的有效共享密钥。

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

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

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

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

php artisan migrate

路由

最后，注意路由：您必须配置 BigBlueButton webhooks 应该击中您的应用程序的 URL。在您的应用程序的路由文件中，您必须将此路由传递给 Route::bigbluebuttonWebhooks()

我喜欢按域名分组功能，所以我建议使用 webhooks/bigbluebutton（特别是如果您计划有更多 webhooks），但这完全取决于您。

# routes\web.php
Route::bigbluebuttonWebhooks('webhooks/bigbluebutton');

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

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

用法

BigBlueButton 会为几种事件类型发送 webhooks。我试图找到所有 BigBLueButton 事件的完整列表，但徒劳无功。如果您有，请告诉我

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

除非发生严重错误，否则此包将始终对 webhook 请求响应 200。发送 200 将防止 BigBlueButton 重复发送相同的事件。所有具有有效签名的 webhook 请求都将记录在 webhook_calls 表中。该表有一个 payload 列，其中保存了整个传入 webhook 的有效负载。

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

该软件包始终将事件转换为小写，因此您的配置密钥也必须是小写的。

注意：根据文档

只有在调用 /hooks/destroy 或如果钩子的回调失败次数太多（约12次）并且持续时间很长（约5分钟）时，才会删除钩子。

特别注意：有效载荷结构

从BigBlueButton发送的有效载荷在某种程度上被分为三个部分。默认情况下，软件包将使用 $request->input() 将BBB发送回您的有效载荷存储在包中。如果您想转换有效载荷，可能需要使用自定义模型。高级用法

此软件包有两种方法使您能够处理webhook请求：您可以选择排队一个作业或监听软件包将触发的事件。

使用作业处理webhook请求

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

<?php

namespace App\Jobs\BigBlueButtonWebhooks;

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

class HandleDelivered 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请求的响应时间。这允许您处理更多的BigBlueButton webhook请求并避免超时。

花点时间查看 BinaryCats\BigBlueButtonWebhooks\Tests\PayloadDefinition::getPayloadDefinition()，以了解有效载荷的结构。

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

// config/bigbluebutton-webhooks.php

'jobs' => [
    'meeting-created' => \App\Jobs\BigBlueButtonWebhooks\MeetingCreatedJob::class,
],

使用事件处理webhook请求

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

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

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

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

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

<?php

namespace App\Listeners;

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

class MeetingCreatedListener 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请求的响应时间。这允许您处理更多的BigBlueButton webhook请求并避免超时。

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

高级用法

转换有效载荷

如果您想更改如何将有效载荷保存到数据库中，例如，将 event 名称作为顶级元素，您可能需要使用自定义模型

use Illuminate\Http\Request;
use Illuminate\Support\Arr;
use Spatie\WebhookClient\Models\WebhookCall as Model;
use Spatie\WebhookClient\WebhookConfig;

class WebhookCall extends Model
{
    /**
     * @param  \Spatie\WebhookClient\WebhookConfig  $config
     * @param  \Illuminate\Http\Request  $request
     * @return \Spatie\WebhookClient\Models\WebhookCall
     */
    public static function storeWebhook(WebhookConfig $config, Request $request): Model
    {
        // bigblubutton payload is build in expectation of multiple events
        $payload = $request->input();
        // transform event
        if ($event = Arr::get($payload, 'event', null) and is_string($event)) {
            $payload['event'] = json_decode($event, true);
        }
        // take the headers form the top
        $headers = self::headersToStore($config, $request);
        // parse and return
        return self::create([
            'name' => $config->name,
            'url' => $request->fullUrl(),
            'headers' => $headers,
            'payload' => $payload,
        ]);
    }
}

并在 bitbluebutton-webhooks.model 配置键中注册它。以上示例基于

重试处理webhook

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

use Spatie\WebhookClient\Models\WebhookCall;
use BinaryCats\BigBlueButtonWebhooks\ProcessBigBlueButtonWebhookJob;

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

执行自定义逻辑

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

以下是一个示例

use BinaryCats\BigBlueButtonWebhooks\ProcessBigBlueButtonWebhookJob;

class MyCustomBigBlueButtonWebhookJob extends ProcessBigBlueButtonWebhookJob
{
    public function handle()
    {
        // do some custom stuff beforehand

        parent::handle();

        // do some custom stuff afterwards
    }
}

处理多个签名密钥

当需要处理多个端点和密钥时，可能需要配置该包。以下是配置该行为的方法。

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

Route::bigbluebuttonWebhooks('webhooks/bigbluebutton/{configKey}');

或者，如果您正在手动定义路由，可以像这样添加 configKey

Route::post('webhooks/bigbluebutton/{configKey}', 'BinaryCats\BigBlueButtonWebhooks\BigBlueButtonWebhooksController');

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

示例配置可能如下所示

// secret for when BigBlueButton posts to webhooks/bigbluebutton/account
'signing_secret_account' => 'whsec_abc',
// secret for when BigBlueButton posts to webhooks/bigbluebutton/my-named-secret
'signing_secret_my-named-secret' => 'whsec_123',

关于BigBlueButton

BigBlueButton 是一个开源的在线学习网络会议系统。

变更日志

请参阅 CHANGELOG 了解最近更改的详细信息。

测试

composer test

贡献

请参阅 CONTRIBUTING 了解详情。

安全

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

明信片软件

您可以免费使用此包，但如果它进入您的生产环境，我们非常感激您从家乡给我们寄来一张明信片，并提及您正在使用我们的哪个包。

鸣谢

向 Spatie 表示敬意，他们的工作为我们提供了巨大的灵感。

支持我们

Binary Cats 是一家位于美国伊利诺伊州的网络设计公司。

许可证

MIT 许可证（MIT）。请参阅许可证文件了解更多信息。

binary-cats / laravel-bigbluebutton-webhooks

维护者

详细信息