README

在 Laravel php 框架中处理 AWS SES webhooks。

安装

您可以通过 composer 安装此软件包

composer require "ankurk91/laravel-ses-webhooks"

服务提供器将自动注册自身。

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

php artisan vendor:publish --provider="Ankurk91\SesWebhooks\SesWebhooksServiceProvider"

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

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

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

php artisan migrate

接下来，为了路由，将此路由（访客）添加到您的 routes/web.php

Route::sesWebhooks('/webhooks/ses');

幕后，这将注册一个由此软件包提供的控制器的 POST 路由。接下来，您必须将此路由添加到您的 VerifyCsrfToken 中间件的 except 数组中

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

建议设置一个队列工作者来处理传入的 webhooks。

为 SES webhooks 准备您的 AWS 控制台

假设您已经在您的应用程序中设置了并运行了 SES 服务
创建一个配置集
将 SNS 作为事件目标
为该新创建的 SNS 主题选择 HTTP 作为交付方法
将 webhook URL 指定为 ${APP_URL}/webhooks/ses
此软件包应自动确认订阅
您需要在您的 config/services.php 中指定配置集名称

 'ses' => [
        'key' => env('AWS_ACCESS_KEY_ID'),
        'secret' => env('AWS_SECRET_ACCESS_KEY'),
        'region' => env('AWS_DEFAULT_REGION', 'us-east-1'),
        'options' => [
            'ConfigurationSetName' => env('AWS_SES_CONFIGURATION_SET'),
        ],
    ],

使用方法

通过此软件包处理传入 webhooks 有两种方式。

1 - 使用作业处理 webhook 请求

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

<?php

namespace App\Jobs\Webhooks\SES;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Queue\SerializesModels;
use Illuminate\Support\Arr;
use Spatie\WebhookClient\Models\WebhookCall;

class BounceHandlerJob implements ShouldQueue
{
    use SerializesModels;

    public function __construct(protected WebhookCall $webhookCall)
    {
        //
    }

    public function handle()
    {
        $message = $this->webhookCall->payload['Message'];
        
        if (Arr::get($message, 'bounce.bounceType') !== 'Permanent') return;

        foreach ($message['bounce']['bouncedRecipients'] as $recipient) {
            // todo do something with $recipient['emailAddress']
        }
    }
}

创建您的作业后，您必须在 config/ses-webhooks.php 配置文件中的 jobs 数组中注册它。键应为小写，空格应替换为 _。值应为完全限定的类名。

<?php

return [
     'jobs' => [
          'bounce' => \App\Jobs\Webhooks\SES\BounceHandlerJob::class,
     ],
];

2 - 使用事件和监听器处理 webhook 请求

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

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

您可以通过在您的 EventServiceProvider 类中注册监听器来监听此类事件。

protected $listen = [
    'ses-webhooks::complaint' => [
        App\Listeners\SES\ComplaintListener::class,
    ],
];

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

<?php

namespace App\Listeners\SES;

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

class ComplaintListener implements ShouldQueue
{
    public function handle(WebhookCall $webhookCall)
    {
        $message = $webhookCall->payload['Message'];
        
        foreach ($message['complaint']['complainedRecipients'] as $recipient) {
            // todo do something with $recipient['emailAddress']
        }
    }
}

修剪旧 webhooks（可选但推荐）

更新您的 app/Console/Kernel.php 文件如下

use Illuminate\Database\Console\PruneCommand;
use Spatie\WebhookClient\Models\WebhookCall;

$schedule->command(PruneCommand::class, [
            '--model' => [WebhookCall::class]
        ])
        ->onOneServer()
        ->daily()
        ->description('Prune webhook_calls.');

这将删除超过 30 天的记录，您可以通过发布此配置文件来修改此持续时间。

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

变更日志

有关最近更改的更多信息，请参阅 CHANGELOG

测试

composer test

安全

如果您发现任何安全问题，请通过电子邮件发送到 pro.ankurk1[at]gmail[dot]com 而不是使用问题跟踪器。

ankurk91 / laravel-ses-webhooks

维护者

详细信息