README

在CraftCMS应用程序中处理Stripe网络钩子

Stripe 可以使用网络钩子通知您的应用程序事件。此插件可以帮助您处理这些网络钩子。它默认会验证所有传入请求的Stripe签名。所有有效调用都将记录到数据库中。您可以轻松定义在特定事件触达您的应用程序时应调度的作业或事件。

此插件不会处理网络钩子请求验证后应执行的操作。您仍需自行编写任何工作（例如，关于支付的工作）的代码。

在开始使用此插件之前，我们强烈建议您阅读 Stripe上的网络钩子完整文档。

支持开源。买啤酒。

此插件根据MIT许可证授权，这意味着它是一项完全免费的开放源代码软件，您可以使用它来做任何您想做的事情。如果您正在使用它并希望支持开发，请在我所在的Beerpay上为我买一杯啤酒！

要求

此插件需要Craft CMS 3.0.0。

配置

创建一个包含以下内容的 stripe-webhooks.php 配置文件，或者从此插件的根目录复制一个。

return [
    /*
     * Stripe will sign each webhook using a secret. You can find the used secret at the
     * webhook configuration settings: https://dashboard.stripe.com/account/webhooks.
     */
    'signingSecret' => '',

    /*
     * You can define the job that should be run when a certain webhook hits your application
     * here. The key is the name of the Stripe event type with the `.` replaced by a `_`.
     *
     * You can find a list of Stripe webhook types here:
     * https://stripe.com/docs/api#event_types.
     */
    'jobs' => [
        // 'source_chargeable' => \modules\sitemodule\jobs\StripeWebhooks\HandleChargeableSource::class,
        // 'charge_failed' => \modules\sitemodule\jobs\StripeWebhooks\HandleFailedCharge::class,
    ],

    /*
     * The classname of the model to be used. The class should equal or extend
     * rias\stripewebhooks\records\StripeWebhookCall.
     */
    'model' => \rias\stripewebhooks\records\StripeWebhookCall::class,

    /*
     * The url of the Stripe endpoint you want to use in your application
     */
    'endpoint' => 'stripe-webhooks',
];

在配置文件的 signingSecret 键中，您应添加一个有效的网络钩子密钥。您可以在 Stripe仪表板上的网络钩子配置设置 中找到此密钥。

用法

Stripe将为几种事件类型发送网络钩子。您可以在Stripe文档中找到 事件类型的完整列表。

Stripe将为击中您的应用程序网络钩子URL的所有请求签名。此包将自动验证签名是否有效。如果不有效，则请求可能不是由Stripe发送的。

除非出现严重错误，否则此插件将始终对网络钩子请求响应 200。发送 200 将防止Stripe反复重新发送相同的事件。所有带有有效签名的网络钩子请求都将记录在 stripewebhooks_stripewebhookcall 表中。该表有一个 payload 列，其中保存了传入网络钩子的整个有效负载。

如果签名无效，则请求将不会记录在 stripewebhooks_stripewebhookcall 表中，但会抛出一个 rias\stripewebhooks\exceptions\WebhookFailed 异常。如果网络钩子请求过程中出现错误，抛出的异常将保存在 exception 列中。在这种情况下，控制器将发送 500 而不是 200。

此插件有两种方式可以启用您处理网络钩子请求：您可以选择排队一个作业或监听该包将引发的的事件。

使用作业处理网络钩子请求

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

  <?php
  
  namespace modules\sitemodule\jobs\StripeWebhooks;
  
  use Craft;
  use craft\queue\BaseJob;
  
  class HandleChargeableSource extends BaseJob
  {
      /** @var \rias\stripewebhooks\records\StripeWebhookCall */
      public $model;
  
      public function execute($queue)
      {
          // do your work here
          
          // you can access the payload of the webhook call with `$this->model->payload`
      }
  }

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

// config/stripe-webhooks.php

'jobs' => [
    'source_chargeable' => \modules\sitemodule\jobs\StripeWebhooks\HandleChargeableSource::class,
],

使用事件处理webhook请求

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

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

您可以在插件或模块的初始化函数中添加监听器

public function init()
{
    Event::on(
        \rias\stripewebhooks\records\StripeWebhookCall::class,
        'stripe-webhooks::source.chargeable',
        function (\rias\stripewebhooks\events\WebhookEvent $event) {
            $webhookCall = $event->model;
        }
    );
}

鸣谢

• Spatie的Laravel Stripe Webhooks包
• 所有贡献者