如何配置您的网站以接受来自 Stripe 的 Webhook

Webhook 允许 Stripe 将消息发送回您的 WordPress 网站。对于 WP Simple Pay 的某些功能，例如发送电子邮件、创建分期付款计划、允许客户更新其订阅付款详细信息以及使用其与AffiliateWP 的集成，需要设置 Webhook。

WP Simple Pay 会尝试自动创建 Webhook 终结点。在大多数情况下，不需要像下面那样进行手动配置。

在 Stripe 中添加终结点

要添加相应的 Webhook 终结点，请在您的 Stripe Dashboard 中转到开发人员 → Webhooks。

点击 添加终结点，然后添加在WP Simple Pay → 设置 → Stripe → Webhooks 中找到的 URL。

请勿启用监听已连接账户上的事件，因为这会破坏 WP Simple Pay 的 Webhook 功能。

现在您需要通过点击标记为+选择事件的按钮来添加要监听的特定事件。完成此操作后，您可以将下面列出的每个事件复制并粘贴到 选择要发送的事件 → 搜索事件 搜索框中。

搜索每个术语后，点击复选框将其添加，然后搜索其他术语。在选中下面列出的所有事件之前，请勿点击添加事件：

• payment_intent.processing
• payment_intent.succeeded
• charge.failed
• charge.refunded
• charge.succeeded
• checkout.session.completed
• customer.subscription.deleted
• customer.subscription.updated
• invoice.payment_succeeded
• invoice.upcoming

本文档底部显示了有关这些事件各自功能的详细信息。

完成添加事件后，点击 添加终结点 以完成此过程。添加终结点后，您应该会在 Webhook 设置中看到新列出的 URL。

配置 Webhook 签名密钥

Stripe 可以对其发送到您端点的 webhook 事件进行签名，以增强安全性，我们强烈建议您进行设置。

为此，请从您的 仪表板的 webhook 设置 中检索您端点的密钥。选择您要获取密钥的已添加端点，然后点击 显示 按钮。

然后从 Stripe 仪表板复制签名密钥，返回到 WordPress 管理后台的 WP Simple Pay → 设置 → Stripe → Webhooks，然后将其粘贴到当前付款模式的 端点密钥 文本框中。

在测试模式下重复

还必须在测试模式下创建 webhook 端点。切换 Stripe 仪表板右上角的 测试模式 开关，然后重复上述步骤。

事件类型说明

invoice.payment_succeeded

• 用于增加分期付款计划并为订阅发送“付款确认”和“付款通知” 电子邮件。
• 公开 simpay_webhook_subscription_created 操作，以便在成功创建订阅后进行进一步处理。
• 公开 simpay_webhook_invoice_payment_succeeded 操作，以便在处理发票后进行进一步处理。

<?php
add_action(
	'simpay_webhook_subscription_created',
	/**
	 * Fires when a subscription is created in Stripe.
	 * 
	 * @param \SimplePay\Vendor\Stripe\Event        $event Stripe webhook event.
	 * @param \SimplePay\Vendor\Stripe\Subscription $subscription Stripe Subscription.
	 */
	function( $event, $subscription ) {
		// Do something.
	},
	10,
	2
);

<?php
add_action(
	'simpay_webhook_invoice_payment_succeeded',
	/**
	 * Fires when a subscription invoice payment has succeeded.
	 * Does not fire for the subscription creation (first) invoice.
	 * 
	 * @param \SimplePay\Vendor\Stripe\Event        $event Stripe webhook event.
	 * @param \SimplePay\Vendor\Stripe\Invoice      $invoice Stripe Invoice object.
	 * @param \SimplePay\Vendor\Stripe\Subscription $subscription Stripe Subscription object.
	 */
	function( $event, $invoice, $subscription ) {
		// Do something.
	},
	10,
	3
);

了解如何添加自定义代码 →

payment_intent.succeeded

• 为一次性付款发送“付款确认”和“付款通知” 电子邮件。
• 公开 simpay_webhook_payment_intent_succeeded 操作，以便在付款成功后进行进一步处理

<?php
add_action(
	'simpay_webhook_payment_intent_succeeded',
	/**
	 * Fires when a one-time payment has succeeded.
	 * 
	 * @param \SimplePay\Vendor\Stripe\Event         $event Stripe webhook event.
	 * @param \SimplePay\Vendor\Stripe\PaymentIntent $paymentintent Stripe PaymentIntent.
	 */
	function( $event, $paymentintent ) {
		// Do something.
	},
	10,
	2
);

了解如何添加自定义代码 →

invoice.upcoming

• 发送“即将到来的发票” 电子邮件提醒以更新付款方式。 了解更多

checkout.session.completed

• 用于删除生成的已放弃的 Stripe Checkout 记录。
• 公开 simpay_webhook_checkout_session_completed 操作，以便在需要时进行进一步处理。

charge.succeeded

• 为使用 ACH 直接付款的一次性付款发送“付款确认”和“付款通知” 电子邮件。
• 公开 simpay_webhook_charge_succeeded 操作，以便在付款成功后进行进一步处理

charge.failed

• 公开 simpay_webhook_charge_failed 操作，以便在付款失败后进行进一步处理。

常见问题解答

Webhook 是必需的吗？

处理付款不需要 Webhook，并且当 Webhook 失败时并不表示付款处理失败。但是，Webhook 用于支持欺诈检测、电子邮件收据、即将到来的发票通知和分期付款计划管理等功能。

使用欺诈检测时的电子邮件验证需要 Webhook。

即使您目前没有使用这些功能，也强烈建议您确保已正确配置 webhook 端点，以避免将来决定启用这些功能时或 WP Simple Pay 为未来功能需要这些功能时造成混淆。

为什么我看到“WP Simple Pay 可能无法正常运行。”

WP Simple Pay 会尝试提醒您 webhook 端点可能配置错误或出错，以避免中断使用 webhook 功能的功能（电子邮件、分期付款计划等）。如果 WP Simple Pay 无法验证预期的 webhook 事件，您将在插件设置中看到一个通知气泡和错误消息“WP Simple Pay 可能无法正常运行。”

如何修复配置错误的 webhook 端点？

要解决可能配置错误的 webhook 端点，请在您的 Stripe 控制台中访问“开发者 → Webhooks”（如果您处于测试模式，请查看您的测试模式端点）。

在“托管端点”下，您应该会看到一个包含 WP Simple Pay webhook 事件接收器的条目：“wp-json/wpsp/v1/webhook-receiver”。如果您没有看到此端点，请完成本文开头概述的配置步骤。

点击 WP Simple Pay 端点 URL 可查看端点的配置。在这里，您将找到已发送到该端点的 webhook 事件列表。

点击“失败”选项卡可列出所有失败的事件。

如果您有失败的 webhook 事件，选择其中一个条目将显示从端点 URL 收到的响应。此响应通常包含有关端点为何未能处理该事件的信息，位于“响应”部分。

无法连接到远程主机

Stripe 无法与您的服务器通信。请确保您的 Web 服务器正在响应请求，特别是能够响应 Stripe 的任何完全限定域名和 IP 地址。

未找到与有效负载的预期签名匹配的签名

Stripe 无法使用“WP Simple Pay → 设置 → Stripe → Webhooks”中提供的签名密钥来验证 webhook 事件数据。在查看您的 webhook 端点时，点击“签名密钥”下的“显示”，然后更新您在 WP Simple Pay 中为每种付款模式设置的签名密钥。

404 错误 <!DOCTYPE html>

Webhook 端点 URL 不正确，指向 404 未找到页面。访问“WP Simple Pay → 设置 → Stripe → Webhooks”以查找您的 webhook 端点 URL 的正确值，并在 Stripe 中更新端点。

我已经验证了我的端点设置，为什么仍然看到错误？

WP Simple Pay 故意对可能的错误配置做出过度响应，以确保真正的错误不会被忽视。但是，仍然有可能收到关于配置错误的 webhook 事件的 误报 通知。如果 Stripe 发送事件数据的时间比平均延迟长，或者在某些 Stripe Checkout 的情况下，站外支付页面被放弃，则可能会发生这种情况。

如果您已 确认您的端点上没有失败的 webhook 端点事件 ，则可以通过以下步骤禁用配置通知。

可以禁用 webhook 配置通知吗？

如前所述，强烈建议正确配置并保持您的 webhook 端点启用。但是， 风险自负 ，如果您不想收到有关任何潜在错误配置或不正确接收的事件的警报，您可以在 WP Simple Pay → 设置 → Stripe → Webhooks 中通过点击 不再显示 来永久关闭通知。