README

webhook是一种应用向另一应用提供特定事件信息的方式。这两个应用之间通过简单的HTTP请求进行通信。

此包允许您在Laravel应用中接收webhooks。它支持验证签名调用，存储有效负载并处理有效负载在队列作业中。

如果您需要发送webhooks，请查看我们的laravel-webhook-server包。

支持我们

我们在创建一流的开放源代码包上投入了大量资源。您可以通过购买我们的付费产品之一来支持我们。

我们非常感谢您从家乡寄来明信片，说明您正在使用我们的哪个包（s）。您可以在我们的联系页面上找到我们的地址。我们将在我们的虚拟明信片墙上发布所有收到的明信片。

安装

您可以通过composer安装此包

composer require spatie/laravel-webhook-client

配置包

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

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

这是将要发布到config/webhook-client.php的文件内容

return [
    'configs' => [
        [
            /*
             * This package support multiple webhook receiving endpoints. If you only have
             * one endpoint receiving webhooks, you can use 'default'.
             */
            'name' => 'default',

            /*
             * We expect that every webhook call will be signed using a secret. This secret
             * is used to verify that the payload has not been tampered with.
             */
            'signing_secret' => env('WEBHOOK_CLIENT_SECRET'),

            /*
             * The name of the header containing the signature.
             */
            'signature_header_name' => 'Signature',

            /*
             *  This class will verify that the content of the signature header is valid.
             *
             * It should implement \Spatie\WebhookClient\SignatureValidator\SignatureValidator
             */
            'signature_validator' => \Spatie\WebhookClient\SignatureValidator\DefaultSignatureValidator::class,

            /*
             * This class determines if the webhook call should be stored and processed.
             */
            'webhook_profile' => \Spatie\WebhookClient\WebhookProfile\ProcessEverythingWebhookProfile::class,

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

            /*
             * The class name of the job that will process the webhook request.
             *
             * This should be set to a class that extends \Spatie\WebhookClient\ProcessWebhookJob.
             */
            'process_webhook_job' => '',
        ],
    ],

在配置文件的signing_secret键中，您应该添加一个有效的webhook密钥。此值应由将向您发送webhooks的应用提供。

此包将尽可能快地尝试存储和响应webhook。通过队列作业处理请求的有效负载。建议不使用sync驱动程序，而使用真实的队列驱动程序。您应该在配置文件的process_webhook_job中指定处理webhook请求的作业。任何扩展Spatie\WebhookClient\ProcessWebhookJob并具有handle方法的类都是有效的作业。

准备数据库

默认情况下，所有webhook调用都将保存在数据库中。

要创建包含webhook调用的表，您必须使用以下命令发布迁移：

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

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

php artisan migrate

注意路由

最后，让我们注意一下路由。在发送webhooks的应用中，您可能已经配置了一个您希望发送webhook请求的URL。在您应用的routes文件中，您必须将此路由传递给Route::webhooks。以下是一个示例

Route::webhooks('webhook-receiving-url');

在幕后，这将向由本包提供的控制器注册一个 POST 路由。因为发送网络钩子到你的应用没有获取 csrf-token 的方法，你必须将此路由添加到 VerifyCsrfToken 中间件的 except 数组中。

protected $except = [
    'webhook-receiving-url',
];

使用方法

安装完成后，让我们看看这个包是如何处理网络钩子的。首先，它会验证请求的签名是否有效。如果不有效，我们将抛出异常并触发 InvalidSignatureEvent 事件。无效签名的请求将不会被存储在数据库中。

接下来，请求将被传递给一个网络钩子配置文件。网络钩子配置文件是一个类，用于确定请求是否应该被您的应用存储和处理。它允许您过滤出对您的应用感兴趣的网络钩子请求。您可以轻松地创建自己的网络钩子配置文件。

如果网络钩子配置文件确定请求应该被存储和处理，我们将首先将其存储在 webhook_calls 表中。之后，我们将新创建的 WebhookCall 模型传递给一个队列作业。大多数发送网络钩子的应用都希望您能快速响应。将实际处理工作移交给他人可以使响应更快。您可以在 webhook-client 配置文件中的 process_webhook_job 中指定哪个作业应该处理网络钩子。如果在队列作业时抛出异常，包会将该异常存储在 WebhookCall 模型的 exception 属性中。

作业分配后，控制器将以 200 状态码响应。

验证传入网络钩子的签名

此包假设传入的网络钩子请求有一个可以用于验证有效负载未被篡改的头部。包含签名的头部的名称可以在配置文件的 signing_secret 键中进行配置。默认情况下，此包使用 DefaultSignatureValidator 来验证签名。这就是该类将如何计算签名的。

$computedSignature = hash_hmac('sha256', $request->getContent(), $configuredSigningSecret);

如果 $computedSignature 与值匹配，请求将被传递给网络钩子配置文件。如果 $computedSignature 与签名头中的值不匹配，包将响应 500 并丢弃请求。

创建自己的签名验证器

签名验证器是任何实现了 Spatie\WebhookClient\SignatureValidator\SignatureValidator 的类。以下是这个接口的外观。

use Illuminate\Http\Request;
use Spatie\WebhookClient\WebhookConfig;

interface SignatureValidator
{
    public function isValid(Request $request, WebhookConfig $config): bool;
}

WebhookConfig 是一个数据传输对象，它允许您轻松获取网络钩子请求的配置（包含包含签名的头部的名称和秘密）。

创建自己的 SignatureValidator 后，您必须在 webhook-client 配置文件中的 signature_validator 中注册它。

确定哪些网络钩子请求应该被存储和处理

传入网络钩子请求的签名验证后，请求将被传递给网络钩子配置文件。网络钩子配置文件是一个类，用于确定请求是否应该被存储和处理。如果发送网络钩子的应用发送了您应用不感兴趣的网络钩子请求，您可以使用这个类来过滤掉这样的事件。

默认情况下使用的是 \Spatie\WebhookClient\WebhookProfile\ProcessEverythingWebhookProfile 类。正如其名称所示，这个默认类将确定所有传入的请求都应该被存储和处理。

创建自己的 webhook 配置文件

webhook 配置文件是指实现了 \Spatie\WebhookClient\WebhookProfile\WebhookProfile 的任何类。这个接口看起来是这样的

namespace Spatie\WebhookClient\WebhookProfile;

use Illuminate\Http\Request;

interface WebhookProfile
{
    public function shouldProcess(Request $request): bool;
}

创建自己的 WebhookProfile 后，必须在 webhook-client 配置文件中的 webhook_profile 键中注册它。

存储和处理 webhook

签名验证后，webhook 配置文件确定请求应该被处理，包将存储并处理请求。

请求首先存储在 webhook_calls 表中。这是使用 WebhookCall 模型完成的。

如果您想自定义表名或存储行为中的任何内容，可以让包使用替代模型。可以在 webhook_model 中指定 webhook 存储模型。确保您的模型扩展 Spatie\WebhookClient\Models\WebhookCall。

您可以通过覆盖 WebhookCall 的 storeWebhook 方法来更改 webhook 的存储方式。在 storeWebhook 方法中，您应该返回一个已保存的模型。

接下来，新创建的 WebhookCall 模型将被传递到队列作业中，该作业将处理请求。任何扩展 \Spatie\WebhookClient\ProcessWebhookJob 的类都是有效的作业。以下是一个示例

namespace App\Jobs;

use \Spatie\WebhookClient\ProcessWebhookJob as SpatieProcessWebhookJob;

class ProcessWebhookJob extends SpatieProcessWebhookJob
{
    public function handle()
    {
        // $this->webhookCall // contains an instance of `WebhookCall`
    
        // perform the work here
    }
}

您应该在 webhook-client 配置文件的 process_webhook_job 中指定作业的类名。

处理来自多个应用的 incoming webhook 请求

此包允许从多个不同的应用接收 webhook。让我们看看一个示例配置文件，我们在其中添加了对两个 webhook URL 的支持。为了简洁起见，所有配置中的注释都已删除。

return [
    'configs' => [
        [
            'name' => 'webhook-sending-app-1',
            'signing_secret' => 'secret-for-webhook-sending-app-1',
            'signature_header_name' => 'Signature-for-app-1',
            'signature_validator' => \Spatie\WebhookClient\SignatureValidator\DefaultSignatureValidator::class,
            'webhook_profile' => \Spatie\WebhookClient\WebhookProfile\ProcessEverythingWebhookProfile::class,
            'webhook_model' => \Spatie\WebhookClient\Models\WebhookCall::class,
            'process_webhook_job' => '',
        ],
        [
            'name' => 'webhook-sending-app-2',
            'signing_secret' => 'secret-for-webhook-sending-app-2',
            'signature_header_name' => 'Signature-for-app-2',
            'signature_validator' => \Spatie\WebhookClient\SignatureValidator\DefaultSignatureValidator::class,
            'webhook_profile' => \Spatie\WebhookClient\WebhookProfile\ProcessEverythingWebhookProfile::class,
            'webhook_model' => \Spatie\WebhookClient\Models\WebhookCall::class,
            'process_webhook_job' => '',
        ],
    ],
];

注册包的路由时，应将配置的 name 作为第二个参数传递。

Route::webhooks('receiving-url-for-app-1', 'webhook-sending-app-1');
Route::webhooks('receiving-url-for-app-2', 'webhook-sending-app-2');

在没有控制器的情况下使用包

如果您不想使用宏提供的路由和控制器，可以程序化地将对 webhook 的支持添加到自己的控制器中。

Spatie\WebhookClient\WebhookProcessor 是一个类，它验证签名、调用 web 配置文件、存储 webhook 请求并启动队列作业以处理存储的 webhook 请求。此包提供的控制器也使用该类在底层。

它可以用这种方式使用

$webhookConfig = new \Spatie\WebhookClient\WebhookConfig([
    'name' => 'webhook-sending-app-1',
    'signing_secret' => 'secret-for-webhook-sending-app-1',
    'signature_header_name' => 'Signature',
    'signature_validator' => \Spatie\WebhookClient\SignatureValidator\DefaultSignatureValidator::class,
    'webhook_profile' => \Spatie\WebhookClient\WebhookProfile\ProcessEverythingWebhookProfile::class,
    'webhook_model' => \Spatie\WebhookClient\Models\WebhookCall::class,
    'process_webhook_job' => '',
]);

(new \Spatie\WebhookClient\WebhookProcessor($request, $webhookConfig))->process();

测试

composer test

更新日志

有关最近更改的更多信息，请参阅更新日志。

贡献

有关详细信息，请参阅贡献。

安全

如果您发现任何安全相关的问题，请通过电子邮件发送给 freek@spatie.be，而不是使用问题跟踪器。

明信片软件

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

我们的地址是：Spaetie, Samberstraat 69D, 2060 安特卫普，比利时。

我们将所有收到的明信片发布在我们的公司网站上。

致谢

许可证

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

磨石 / laravel-webhook-client

维护者

详细信息