README

Lob.com 为处理个性化贺卡、信件和支票等提供了强大的 API，并支持全面的单件邮件跟踪和分析。Lob.com 还可以通过 webhooks 通知您的应用程序邮件事件。此包可以帮助您处理这些 webhooks。它将自动验证所有传入请求的 Lob.com 签名。所有有效的调用都将记录到数据库中。您可以在特定事件触发时轻松定义作业或事件。

此包不会处理在验证 webhook 请求后和调用正确作业或事件后应该执行的操作。您仍然需要自行编写任何工作代码（例如，关于支付的工作）。

在使用此包之前，我们强烈建议您阅读Lob.com 上的有关 webhooks 的完整文档。

此包几乎是 spatie/laravel-stripe-webhooks 的逐行适配副本，这是一个绝对惊人的spatie/laravel-stripe-webhooks。给他们你的爱！

安装

您可以通过 composer 安装此包

composer require binary-cats/laravel-lob-webhooks

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

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

php artisan vendor:publish --provider="BinaryCats\LobWebhooks\LobWebhooksServiceProvider" --tag="config"

这是将发布到 config/lob-webhooks.php 的配置文件内容

return [

    /*
     * Lob.com will sign each webhook using a secret. You can find the used secret at the
     * webhook configuration settings: https://dashboard.lob.com/#/webhooks/create.
     */
    'signing_secret' => env('LOB_WEBHOOK_SECRET'),

    /*
     * You can define the job that should be run when a certain webhook hits your application
     * here. The key is the name of the Lob.com event type with the `.` replaced by a `_`.
     *
     * You can find a list of Lob.com webhook types here:
     * https://lob.com/docs#all_event_types
     * 
     * The package will automatically convert the keys to lowercase, but you should
     * be congnisant of the fact that array keys are case sensitive
     */
    'jobs' => [
        // 'letter_delivered' => \BinaryCats\LobWebhooks\Jobs\HandleDelivered::class,
    ],

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

    /*
     * The classname of the model to be used. The class should equal or extend
     * BinaryCats\LobWebhooks\ProcessLobWebhookJob
     */
    'process_webhook_job' => \BinaryCats\LobWebhooks\ProcessLobWebhookJob::class,
];

在配置文件的 signing_secret 键中，您应该添加一个有效的 webhook 密钥。密钥对每个 webhook 是唯一的，可以在仪表板中相应 webhook 的详细信息页面找到。仪表板中的 webhook。

如果您已安装 Spatie\WebhookClient，则可以跳过迁移

接下来，您必须使用以下命令发布迁移

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

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

php artisan migrate

路由

最后，注意路由：在 Lob.com 仪表板中，您必须配置 Lob.com webhooks 应该击中您的应用程序的 URL。在您的应用程序的路由文件中，您必须将此路由传递给 Route::lobWebhooks()

我喜欢按域名分组功能，因此建议使用 webhooks/lob

Route::lobWebhooks('webhooks/lob');

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

protected $except = [
    'webhooks/lob',
];

用法

Lob.com 会为多种事件类型发送 webhooks。您可以在 Lob.com 文档中找到事件类型的完整列表。

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

除非发生严重错误，否则此包将始终以 200 响应 webhook 请求。发送 200 将防止 Lob.com 反复重新发送相同的事件。所有具有有效签名的 webhook 请求都将记录在 webhook_calls 表中。该表有一个 payload 列，其中保存了传入 webhook 的整个有效负载。

如果签名无效，请求将不会记录在 webhook_calls 表中，而是会抛出 BinaryCats\LobWebhooks\Exceptions\WebhookFailed 异常。如果在 webhook 请求过程中出现问题，抛出的异常将被保存到 exception 列表中。在这种情况下，控制器将发送 500 而不是 200。

此包提供了两种处理 webhook 请求的方法：您可以选择排队一个作业或监听包将触发的事件。

包将始终将事件转换为小写 - 因此您的配置密钥也必须是小写。

使用作业处理 webhook 请求

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

namespace App\Jobs\LobWebhooks;

use Illuminate\Bus\Queueable;
use Illuminate\Queue\SerializesModels;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;
use Spatie\WebhookClient\Models\WebhookCall;

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

    /** @var \Spatie\WebhookClient\Models\WebhookCall */
    public $webhookCall;

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

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

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

Spatie 强烈建议您将该作业设置为可排队，因为这将最小化 webhook 请求的响应时间。这允许您处理更多的 Lob.com webhook 请求并避免超时。

创建您的作业后，必须在 lob-webhooks.php 配置文件中的 jobs 数组中注册它。键应该是 Lob.com 事件类型的名称，但用 . 替换为 _。值应该是完全限定的类名。

// config/lob-webhooks.php

'jobs' => [
    'letter_created' => \App\Jobs\Lob\Webhooks\HandleLetterCreatedJob::class,
],

使用事件处理 webhook 请求

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

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

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

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

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

namespace App\Listeners;

use Illuminate\Contracts\Queue\ShouldQueue;
use Spatie\WebhookClient\Models\WebhookCall;

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

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

Spatie 强烈建议您将事件监听器设置为可排队，因为这将最小化 webhook 请求的响应时间。这允许您处理更多的 Lob.com webhook 请求并避免超时。

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

高级用法

重试处理 webhook

所有传入的 webhook 请求都会写入数据库。这在处理 webhook 调用时出现问题时非常有价值。您可以在调查并修复失败原因后，轻松地重试处理 webhook 调用，如下所示：

use BinaryCats\LobWebhooks\ProcessLobWebhookJob;
use Spatie\WebhookClient\Models\WebhookCall;

dispatch(new ProcessLobWebhookJob(WebhookCall::find($id)));

执行自定义逻辑

您可以通过使用自己的作业类来添加一些应该在排队的作业调度之前和/或之后执行的自定义逻辑。您可以通过在 lob-webhooks 配置文件中的 process_webhook_job 键中指定自己的作业类来实现这一点。该类应扩展 BinaryCats\LobWebhooks\ProcessLobWebhookJob。

以下是一个示例：

use BinaryCats\LobWebhooks\ProcessLobWebhookJob;

class MyCustomLobWebhookJob extends ProcessLobWebhookJob
{
    public function handle()
    {
        // do custom stuff beforehand

        parent::handle();

        // do custom stuff afterwards
    }
}

处理多个签名密钥

当需要时，可能需要包处理多个端点和密钥。以下是配置该行为的步骤。

如果您正在使用 Route::lobWebhooks 宏，您可以按照如下方式附加 configKey（假设您的传入路由 URL 为 webhooks/lob）：

Route::lobWebhooks('webhooks/lob/{configKey}');

或者，如果您正在手动定义路由，您可以添加 configKey 如此：

Route::post('webhooks/lob/{configKey}', 'BinaryCats\LobWebhooks\LobWebhooksController');

如果存在此路由参数，验证中间件将使用不同的配置密钥查找密钥，通过给定的参数值附加到默认配置密钥。例如，如果 Lob.com 发送到 lob-webhook-url/my-named-secret，您将添加一个名为 signing_secret_my-named-secret 的新配置。

示例配置可能如下所示：

// secret for when Lob.com posts to webhooks/lob/account
'signing_secret_account' => 'whsec_abc',
// secret for when Lob.com posts to webhooks/lob/connect
'signing_secret_connect' => 'whsec_123',

关于 Lob.com

Lob.com 为企业提供 API，以增强线下和线上世界的连接性。

变更日志

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

测试

composer test

贡献

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

安全

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

明信片软件

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

鸣谢

向Spatie表示敬意，他们的工作为我们提供了巨大的灵感。

支持我们

Binary Cats是一家位于美国伊利诺伊州的网络设计公司。

许可证

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

binary-cats / laravel-lob-webhooks

维护者

详细信息