README

Oh Dear可以使用webhooks通知您的应用程序事件。这个包可以帮助您处理这些webhooks。默认情况下，它会验证所有传入请求的Oh Dear签名。您可以轻松定义当特定事件击中您的应用程序时应分发的作业或事件。

此包不会处理验证webhook请求并调用正确的作业或事件之后应该做什么。

安装

$ composer require ohdearapp/laravel-ohdear-webhooks

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

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

$ php artisan vendor:publish --provider="OhDear\LaravelWebhooks\OhDearWebhooksServiceProvider" --tag="config"

这是将在config/ohdear-webhooks.php中发布的配置文件内容

return [

    /*
     * Oh dear will sign webhooks using a secret. You can find the secret used at the webhook
     * configuration settings: <?php echo config('app.url'); ?>/team-settings/notifications#webhooks
     */
    'signing_secret' => env('OH_DEAR_SIGNING_SECRET'),

    /*
     * Here you can define the job that should be run when a certain webhook hits your .
     * application.
     *
     * You can find a list of Oh dear webhook types here:
     * <?php echo config('app.url'); ?>/docs/webhooks/events
     */
    'jobs' => [
        // 'uptimeCheckFailed' => \App\Jobs\LaravelWebhooks\HandleFailedUptimeCheck::class,
        // 'uptimeCheckRecovered' => \App\Jobs\LaravelWebhooks\HandleRecoveredUptimeCheck::class,
        // ...
    ],
];

在配置文件的signing_secret键中，您指定签名密钥。您可以在通知设置屏幕上的团队webhooks设置中找到正确的密钥。

最后，注意路由：在Oh Dear通知设置中，您必须配置Oh Dear webhooks应该击中您的应用程序的URL。在您的应用程序的路由文件中，您必须将此路由传递给Route::ohDearWebhooks

Route::ohDearWebhooks('webhook-route-configured-at-the-ohdear-dashboard');

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

protected $except = [
    'webhook-route-configured-at-the-ohdear-dashboard',
];

用法

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

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

除非发生错误，此包将对webhook请求响应200。发送200将防止Oh Dear重新发送相同的事件。

如果签名无效，将抛出OhDear\OhDearWebhooks\WebhookFailed异常。

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

使用作业处理webhook请求

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

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Queue\SerializesModels;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;
use OhDear\LaravelWebhooks\OhDearWebhookCall;

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

    /** @var \OhDear\LaravelWebhooks\OhDearWebhookCall */
    public $webhookCall;

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

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

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

我们强烈建议您将此作业标记为可排队，因为这将最小化webhook请求的响应时间。这允许您处理更多的oh dear webhook请求并避免超时。

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

// config/ohdear-webhooks.php

'jobs' => [
    'uptimeCheckFailed' => \App\Jobs\ohdearWebhooks\HandleFailedUptimeCheck::class,
    'uptimeCheckRecovered' => \App\Jobs\ohdearWebhooks\HandleRecoveredUptimeCheck::class,
],

使用事件处理webhook请求

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

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

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

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

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

namespace App\Listeners;

use Illuminate\Contracts\Queue\ShouldQueue;
use OhDear\LaravelWebhooks\OhDearWebhookCall;

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

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

我们强烈建议您使事件监听器可排队，因为这将最小化 webhook 请求的响应时间。这允许您处理更多 Oh Dear webhook 请求并避免超时。

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

使用 OhDearWebhookCall

如上所述，您的事件或作业将接收一个 OhDear\LaravelWebhooks\OhDearWebhookCall 实例。

您可以通过调用以下方法来访问原始负载：

$ohDearWebhookCall->payload; // returns an array;

或者，您可以选择获取更具体的信息

$ohDearWebhookCall->type(); // returns the type of the webhook (eg: 'uptimeCheckFailed');
$ohDearWebhookCall->site(); // returns an array with all the attribute of the site;
$ohDearWebhookCall->run(); // returns an array with all the attribute of the run;
$ohDearWebhookCall->dateTime(); // returns an string with a dateTime (Ymdhis) when Oh Dear generated this webhook call;

贡献

有关详细信息，请参阅CONTRIBUTING。

安全性

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

鸣谢

• Freek Van der Herten
• Mattias Geniar
• 所有贡献者

许可证

MIT 许可证（MIT）。有关更多信息，请参阅许可证文件。