README

此包将 spatie/laravel-webhook-server 适配到 Lumen 使用。

安装

您可以通过 composer 安装此包

composer require jmsfwk/lumen-webhook-server

将服务提供者添加到您的 app.php 文件

$app->register(Jmsfwk\WebhookServer\WebhookServerServiceProvider::class);

默认情况下，此包使用队列重试失败的 webhook 请求。请确保在非本地环境中设置除 sync 以外的真实队列。

用法

这是调用 webhook 的最简单方法

WebhookCall::create()
   ->url('https://other-app.com/webhooks')
   ->payload(['key' => 'value'])
   ->useSecret('sign-using-this-secret')
   ->dispatch();

这将向 https://other-app.com/webhooks 发送 POST 请求。请求正文将是传递给 payload 的数组的 JSON 编码版本。请求将包含一个名为 Signature 的头，其中包含接收应用可以使用以验证 payload 未被篡改的签名。

如果接收应用没有以以 2 开头的响应代码响应，则包将在 10 秒后重试调用 webhook。如果第二次尝试失败，则包将在 100 秒后尝试最终调用 webhook。如果该尝试失败，将引发 FinalWebhookCallFailedEvent。

请求签名的工作原理

在设置过程中，通常会在您的应用和希望接收 webhook 的应用之间生成、存储和共享一个密钥。密钥的生成可以使用 Illuminate\Support\Str::random() 完成，但这完全取决于您。该包将使用密钥对 webhook 调用进行签名。

默认情况下，该包将添加一个名为 Signature 的头，其中包含接收应用可以使用以验证 payload 未被篡改的签名。以下是计算该签名的步骤

// payload is the array passed to the `payload` method of the webhook
// secret is the string given to the `signUsingSecret` method on the webhook.

$payloadJson = json_encode($payload); 

$signature = hash_hmac('sha256', $payloadJson, $secret);

自定义签名请求

如果您想自定义签名过程，可以创建自己的自定义签名者。签名者是实现 Spatie\WebhookServer\Signer 的任何类。

该接口看起来像这样。

namespace Spatie\WebhookServer\Signer;

interface Signer
{
    public function signatureHeaderName(): string;

    public function calculateSignature(array $payload, string $secret): string;
}

创建您的签名者后，您可以在 webhook-server 配置文件的 signer 键中指定其类名。然后，您的签名者将在所有 webhook 调用中默认使用。

您还可以为特定的 webhook 调用指定签名者

WebhookCall::create()
    ->signUsing(YourCustomSigner::class)
    ...
    ->dispatch();

如果您想自定义头名称，不需要使用自定义签名者，但可以更改 webhook-server 配置文件中的 signature_header_name 中的值。

重试失败的 webhook

当我们发送 webhook 的应用未能以 2xx 状态码发送响应时，该包会将调用视为失败。如果远程应用在 3 秒内没有响应，调用也将被视为失败。

您可以在 webhook-server 配置文件的 timeout_in_seconds 键中配置默认超时。或者，您可以像这样覆盖特定 webhook 的超时

WebhookCall::create()
    ->timeoutInSeconds(5)
    ...
    ->dispatch();

当 webhook 调用失败时，我们将再次尝试调用两次。您可以在配置文件的 tries 键中设置我们默认重试 webhook 调用的次数。或者，您可以像这样指定特定 webhook 的尝试次数

WebhookCall::create()
    ->maximumTries(5)
    ...
    ->dispatch();

为了不频繁打击远程应用，我们将在每次尝试之间等待一段时间。默认情况下，我们在第一次和第二次尝试之间等待10秒，第三次和第四次之间等待100秒，第四次和第五次之间等待1000秒，以此类推。我们将等待的最大秒数是100000，大约是27小时。这种行为是通过默认的ExponentialBackoffStrategy实现的。

您可以通过创建一个实现Spatie\WebhookServer\BackoffStrategy\BackoffStrategy的类来自定义回退策略。这个接口看起来是这样的

namespace Spatie\WebhookServer\BackoffStrategy;

interface BackoffStrategy
{
    public function waitInSecondsAfterAttempt(int $attempt): int;
}

您可以通过在webhook-server配置文件的backoff_strategy中指定其完全限定的类名来将自定义策略设置为默认策略。或者，您可以像这样指定特定webhook的策略。

WebhookCall::create()
    ->useBackoffStrategy(YourBackoffStrategy::class)
    ...
    ->dispatch();

在底层，webhook调用重试是通过使用延迟分发实现的。Amazon SQS仅支持较小的最大延迟。如果您使用Amazon SQS作为队列，请确保您不会以使每次尝试之间有超过15分钟的方式来配置该包。

自定义HTTP动词

默认情况下，所有webhook都将使用post方法。您可以通过在webhook-server配置文件的http_verb键中指定您想要的HTTP动词来自定义。

您还可以通过使用useHttpVerb方法来覆盖特定调用。

WebhookCall::create()
    ->useHttpVerb('get')
    ...
    ->dispatch();

添加额外的头部信息

您可以通过将它们添加到webhook-server配置文件的headers键中来使用额外的头部信息。如果您想为特定webhook添加额外的头部信息，您可以使用withHeaders调用。

WebhookCall::create()
    ->withHeaders([
        'Another Header' => 'Value of Another Header'
    ])
    ...
    ->dispatch();

验证接收应用的SSL证书

当使用以https://开始的URL时，该包将验证接收方的SSL证书是否有效。如果不是，我们将认为webhook调用失败。我们不推荐这样做，但您可以将webhook-server配置文件中的verify_ssl键设置为false来关闭此验证。

您还可以使用doNotVerifySsl方法在每个webhook调用中禁用验证。

WebhookCall::create()
    ->doNotVerifySsl()
    ...
    ->dispatch();

添加元信息

您可以为webhook添加额外的元信息。这些元信息将不会传输，并且仅用于传递给该包触发的事件。

这是添加元信息的方法

WebhookCall::create()
    ->meta($arrayWithMetaInformation)
    ...
    ->dispatch();

添加标签

如果您使用Laravel Horizon作为您的队列，您会很高兴地知道我们支持标签。

要为执行webhook调用的底层作业添加标签，只需在webhook-server配置文件的tags键中指定它们或使用withTags方法

WebhookCall::create()
    ->withTags($tags)
    ...
    ->dispatch();

事件

该包触发以下事件

WebhookCallSucceededEvent：远程应用以2xx响应代码响应。
WebhookCallFailedEvent：远程应用以非2xx响应代码响应，或者根本不响应。
FinalWebhookCallFailedEvent：调用webhook的最后尝试失败。

所有这些事件都有以下属性

httpVerb：执行请求的动词
webhookUrl：请求发送到的URL
payload：使用的有效负载
headers：发送的头部。此数组包括签名头部
meta：通过meta调用传递给webhook的值的数组
tags：使用的标签的数组
attempt：尝试次数
response：由远程应用程序返回的响应。可以是 \GuzzleHttp\Psr7\Response 的实例或 null。

测试

composer test

变更日志

请参阅变更日志获取关于最近更改的更多信息。

贡献

请参阅贡献指南获取详细信息。

安全

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

鸣谢

支持 Spatie

Spatie 是一家位于比利时安特卫普的网站设计公司。您可以在他们的网站上找到所有开源项目的概述在这里。

如果您也依赖他们的贡献？联系他们并在Patreon上支持他们。

许可证

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

jmsfwk / lumen-webhook-server

维护者

详细信息