README

在 Laravel 应用中接收 webhooks

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

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

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

支持我们

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

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

安装

您可以通过 composer 安装此包

composer require spatie/laravel-webhook-client

配置包

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

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

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

return [
    'configs' => [
        [
            /*
             * This package supports 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,

            /*
             * This class determines the response on a valid webhook call.
             */
            'webhook_response' => \Spatie\WebhookClient\WebhookResponse\DefaultRespondsTo::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\Jobs\ProcessWebhookJob.
             */
            'process_webhook_job' => '',
        ],
    ],

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

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

准备数据库

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

要创建包含 webhook 调用的表，您必须发布迁移

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

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

php artisan migrate

处理路由

最后，我们来处理路由。在发送 webhooks 的应用程序中，您可能已配置了一个 URL，您希望您的 webhook 请求发送到该 URL。在您应用程序的路由文件中，您必须将此路由传递给 Route::webhooks。以下是一个示例

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

幕后，这将注册一个到由该包提供的控制器的 POST 路由。因为发送 webhooks 到您的应用程序的应用程序没有获取 csrf-token 的方法，所以您必须将此路由添加到 VerifyCsrfToken 中间件的 except 数组中

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

使用

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

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

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

作业分发后，请求将被传递到webhook响应。webhook响应是一个类，用于确定请求的HTTP响应。默认情况下，返回带有200状态码的“ok”消息响应，但您可以轻松地创建您自己的webhook响应。

验证传入webhooks的签名

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

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

如果$computedSignature与值匹配，则请求将通过webhook配置文件传递。如果$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是一个数据传输对象，允许您轻松地拉取配置（包含包含签名的头部名称和机密），用于webhook请求。

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

确定哪些webhook请求应该被存储和处理

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

默认情况下，使用\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键中注册它。

存储和处理webhooks

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

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

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

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

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

namespace App\Jobs;

use Spatie\WebhookClient\Jobs\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 中指定您的作业的类名。

创建自己的 webhook 响应

Webhook 响应是任何实现 \Spatie\WebhookClient\WebhookResponse\RespondsToWebhook 接口的类。这个接口看起来是这样的

namespace Spatie\WebhookClient\WebhookResponse;

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

interface RespondsToWebhook
{
    public function respondToValidWebhook(Request $request, WebhookConfig $config);
}

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

处理来自多个应用的 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_response' => \Spatie\WebhookClient\WebhookResponse\DefaultRespondsTo::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_response' => \Spatie\WebhookClient\WebhookResponse\DefaultRespondsTo::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_response' => \Spatie\WebhookClient\WebhookResponse\DefaultRespondsTo::class,
    'webhook_model' => \Spatie\WebhookClient\Models\WebhookCall::class,
    'process_webhook_job' => '',
]);

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

测试

composer test

变更日志

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

贡献

请参阅 CONTRIBUTING 了解详细信息。

安全

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

明信片软件

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

我们的地址是：Spatie，Kruikstraat 22，2018 安特卫普，比利时。

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

致谢

许可证

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

kbv-vcos / laravel-webhook-client

维护者

详细信息