README

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

此包允许您在 Laravel 应用中接收 webhook。它支持验证签名调用，存储有效载荷并处理有效载荷在排队的工作中。

如果您需要发送 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 密钥。此值应由将发送 webhook 给您的应用程序提供。

此包将尽可能快地存储和响应 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

处理路由

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

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

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

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

使用

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

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

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

在派遣工作后，请求将被传递给webhook响应。webhook响应是一个类，用于确定请求的HTTP响应。默认返回带有200状态码的“ok”消息响应，但您可以轻松创建自己的webhook响应。

验证传入webhook的签名

此包假设传入的webhook请求有一个包含签名，可以用来验证有效负载未被篡改的头部。包含签名的头部名称可以在配置文件的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配置文件是一个类，用于确定请求是否应该被存储和处理。如果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键。

存储和处理webhook

在验证签名并且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 Profile，存储 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 而不是使用问题跟踪器。

Postcardware

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

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

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

鸣谢

许可证

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

asorasoft / laravel-webhook-client

维护者

详细信息