README

SurveyMonkey.com是一家基于云的在线调查开发软件即服务公司。SurveyMonkey还可以使用webhooks通知您的应用程序关于收集者和响应事件。此软件包可以帮助您处理这些webhooks。默认情况下，它将验证所有传入请求的SurveyMonkey签名。所有有效的调用都将记录到数据库中。您可以轻松定义在特定事件击中您的应用程序时应分发的作业或事件。

此软件包不会处理webhook请求验证后应该执行的操作。您仍然需要自己编写任何代码。

在开始使用此软件包之前，我们强烈建议您阅读surveymonkey.com上的完整webhooks文档。

此软件包几乎是逐行复制的绝对惊人的spatie/laravel-stripe-webhooks。给他们一些爱吧！

最后，此软件包假定您正在使用Survey Monkey API版本3。

安装

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

composer require binary-cats/laravel-surveymonkey-webhooks

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

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

php artisan vendor:publish --provider="BinaryCats\SurveyMonkeyWebhooks\SurveyMonkeyWebhooksServiceProvider" --tag="config"

以下是将在config/surveymonkey-webhooks.php中发布的配置文件的内容

return [

    /*
     * Survey Monkey is an online survey development cloud-based software as a service company.
     * You can find the used secret after creating Survey Monkey App: https://developer.surveymonkey.com/
     */
    'signing_secret' => env('SURVEYMONKEY_API_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 Survey Monkey event type with the `.` replaced by a `_`.
     *
     * You can find a list of Survey Monkey webhook types here:
     * https://developer.surveymonkey.com/api/v3/#webhook-callbacks
     */
    'jobs' => [
        // Example:
        // 'response_completed' => \BinaryCats\SurveyMonkeyWebhooks\Jobs\HandleResponseCompleted::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\SurveyMonkeyWebhooks\ProcessSurveyMonkeyWebhookJob
     */
    'process_webhook_job' => \BinaryCats\SurveyMonkeyWebhooks\ProcessSurveyMonkeyWebhookJob::class,
];

在配置文件的signing_secret键中，您应添加有效的webhook密钥。密钥是按应用程序分配的，您可以在您的开发者仪表板上获取它们。

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

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

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

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

php artisan migrate

路由

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

我喜欢按域名分组功能，所以建议使用webwooks/survey-monkey

Route::surveyMonkeyWebhooks('webwooks/survey-monkey');

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

protected $except = [
    'webwooks/survey-monkey',
];

使用方法

Survey Monkey将为几种事件类型发送webhooks。您可以在SurveyMonkey.com文档中找到事件类型的完整列表。

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

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

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

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

使用作业处理webhook请求

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

<?php

namespace App\Jobs\SurveyMonkeyWebhooks;

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

class HandleResponseCompleted 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请求的响应时间。这允许您处理更多的SurveyMonkey.com webhook请求，并避免超时。

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

// config/surveymonkey-webhooks.php

'jobs' => [
    'response_completed' => \BinaryCats\SurveyMonkeyWebhooks\Jobs\HandleResponseCompleted::class,
],

使用事件处理webhook请求

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

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

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

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

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

<?php

namespace App\Listeners;

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

class ResponseCompletedIstener implements ShouldQueue
{
    /** @param Spatie\WebhookClient\Models\WebhookCall */
    public function handle(WebhookCall $webhookCall)
    {
        // do your work here

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

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

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

高级用法

重试处理webhook

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

use Spatie\WebhookClient\Models\WebhookCall;
use BinaryCats\SurveyMonkeyWebhooks\ProcessSurveyMonkeyWebhookJob;

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

执行自定义逻辑

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

以下是一个示例

use BinaryCats\SurveyMonkeyWebhooks\ProcessSurveyMonkeyWebhookJob;

class MyCustomSurvkeyMonkeyWebhookJob extends ProcessSurveyMonkeyWebhookJob
{
    public function handle()
    {
        // do custom stuff beforehand

        parent::handle();

        // do custom stuff afterwards
    }
}

处理多个签名密钥

有时可能需要包处理多个端点和密钥。以下是配置此行为的方法。

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

Route::surveymonkeyWebhooks('webhooks/survey-monkey/{configKey}');

或者，如果您正在手动定义路由，您可以添加configKey如下所示

Route::post('webhook/survey-monkey/{configKey}', 'BinaryCats\SurveyMonkeyWebhooks\SurveyMonkeyWebhooksController');

如果存在此路由参数，验证中间件将使用不同的配置键来查找密钥，通过将给定的参数值附加到默认配置键。例如，如果SurveyMonkey.com向webhooks/survey-monkey/my-named-secret发送，则应添加一个新的配置，名为signing_secret_my-named-secret。

示例配置可能如下所示

// secret for when Survey Monkey posts to webhooks/survey-monkey/account
'signing_secret_account' => 'whsec_abc',
// secret for when Survey Monkey posts to webhooks/survey-monkey/my-named-secret
'signing_secret_my-named-secret' => 'whsec_123',

关于SurveyMonkey.com

SurveyMonkey.com是一家基于云的在线调查开发软件即服务公司。

变更日志

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

测试

composer test

贡献

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

安全

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

Postcardware

您可以使用此软件包，但如果它进入您的生产环境，我们非常希望您从家乡给我们寄一张明信片，并说明您正在使用我们的哪些软件包。

鸣谢

向Spatie表示敬意，他们的工作给我们带来了巨大的灵感。

支持我们

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

许可

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

binary-cats / laravel-surveymonkey-webhooks

维护者

详细信息