README

EasyPost可以使用webhook通知您的应用程序事件。这个包可以帮助您处理这些webhook。所有有效的调用都将记录到数据库中。您可以在特定事件触发您的应用程序时轻松定义作业或事件。

此包不会处理验证webhook请求后应该做什么。您仍然需要自己编写任何工作代码。

在使用此包之前，我们强烈建议您阅读EasyPost上的完整webhook文档。

安装

您可以通过composer安装此包

composer require beaub/laravel-easypost-webhooks

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

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

php artisan vendor:publish --provider="BeauB\EasypostWebhooks\EasypostWebhooksServiceProvider" --tag="config"

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

return [

    /*
     * You can define the job that should be run when a certain webhook hits your application
     * here. The key is the name of the Easypost event description with the `.` replaced by a `_`.
     *
     * You can find a list of Easypost webhook description types here:
     * https://www.easypost.com/docs/api#possible-event-types.
     */
    'jobs' => [
        // 'refund_successful' => \App\Jobs\EasypostWebhooks\HandleSuccessfulRefund::class,
        // 'tracker_created' => \App\Jobs\EasypostWebhooks\HandleTrackerCreated::class,
    ],

    /*
     * The classname of the model to be used. The class should equal or extend
     * BeauB\EasypostWebhooks\EasypostWebhookCall.
     */
    'model' => BeauB\EasypostWebhooks\EasypostWebhookCall::class,
];

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

php artisan vendor:publish --provider="BeauB\EasypostWebhooks\EasypostWebhooksServiceProvider" --tag="migrations"

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

php artisan migrate

最后，处理路由：在Easypost仪表板中，您必须配置Easypost webhook应该击中您的应用程序的URL。在您的应用程序的路由文件中，您必须将该路由传递给Route::easypostWebhooks

Route::easypostWebhooks('webhook-route-configured-at-the-easypost-dashboard');

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

protected $except = [
    'webhook-route-configured-at-the-easypost-dashboard',
];

使用方法

Easypost将为几种事件类型发送webhook。您可以在Easypost文档中找到事件类型的完整列表。

与Stripe不同，Easypost不会对其发送到您的服务器的webhook进行签名。为了确保请求有效，请在您的端点使用基本认证和HTTPS。此包不包括此功能。有关如何安全地保护您的端点，请参阅Lavavel文档中关于[基本认证]的说明（https://laravel.net.cn/docs/5.5/authentication#http-basic-authentication）。

除非发生严重错误，此包总是会以200响应webhook请求。发送200将防止Easypost重复发送相同的事件。所有webhook请求都将记录在easypost_webhook_calls表中。该表有一个payload列，其中保存了传入webhook的全部负载。

如果在webhook请求期间发生错误，抛出的异常将被保存到exception列中。在这种情况下，控制器将发送500而不是200。

此包有两种方式让您处理webhook请求：您可以选择排队一个作业或监听包将引发的的事件。

使用作业处理webhook请求

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

<?php

namespace App\Jobs;

use Illuminate\Bus\Queueable;
use Illuminate\Queue\SerializesModels;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;
use BeauB\EasypostWebhooks\EasypostWebhookCall;

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

    /** @var \BeauB\EasypostWebhooks\EasypostWebhookCall */
    public $webhookCall;

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

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

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

我们强烈建议您将此工作设置为可队列的，因为这将最小化webhook请求的响应时间。这允许您处理更多的Easypost webhook请求并避免超时。

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

// config/easypost-webhooks.php

'jobs' => [
    'tracker_created' => \App\Jobs\EasypostWebhooks\HandleTrackerCreated::class,
],

使用事件处理webhook请求

您可以选择监听此包将要触发的事件，而不是将工作队列化，在接收到webhook请求时执行一些工作。每当有效的请求击中您的应用程序时，此包将触发一个easypost-webhooks::<事件名称>事件。

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

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

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

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

<?php

namespace App\Listeners;

use Illuminate\Contracts\Queue\ShouldQueue;
use BeauB\EasypostWebhooks\EasypostWebhookCall;

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

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

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

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

高级用法

重试处理webhook

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

use BeauB\EasypostWebhooks\EasypostWebhookCall;

EasypostWebhookCall::find($id)->process();

执行自定义逻辑

您可以通过在easypost-webhooks配置文件的model键中指定自己的模型来添加一些应在队列作业调度之前和/或之后执行的自定义逻辑。该类应扩展BeauB\EasypostWebhooks\EasypostWebhookCall。

以下是一个示例

use BeauB\EasypostWebhooks\EasypostWebhookCall;

class MyCustomWebhookCall extends EasyposteWebhookCall
{
    public function process()
    {
        // do some custom stuff beforehand

        parent::process();

        // do some custom stuff afterwards
    }
}

变更日志

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

测试

composer test

贡献

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

致谢

此包是从laravel-stripe-webhooks包修改而来，并由Beau Buehler重新发布，以与Easypost webhook一起使用。

原始作品

非常感谢Sebastiaan Luca慷慨分享他的Stripe webhook解决方案，这激发了此包的灵感。

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。

beaub / laravel-easypost-webhooks

维护者

详细信息