在 Webhook 端点中接收 Stripe 事件

在构建 Stripe 集成时，您可能希望在您的 Stripe 账户中有事件发生时，您的应用程序可以接收它们，以便您的后端系统可以执行相应操作。

创建一个事件接收端，以接收 HTTPS Webhook 端点上的事件。在您注册 Webhook 端点后，当您的 Stripe 账户有事件发生时，Stripe 可以将实时事件数据推送到您的应用程序的 Webhook 端点。Stripe 用 HTTPS 将 Webhook 事件以包含事件对象的 JSON 有效载荷发送到您的应用程序。

接收 Webhook 事件可帮助您响应异步事件，例如客户的银行确认付款、客户对收款提出争议或经常性付款成功。

还可以在具有事件接收端的 Amazon EventBridge 中接收事件。

开始

要开始在您的应用程序中接收 Webhook 事件：

1. 创建一个 Webhook 端点处理程序来接收事件数据的 POST 请求。
2. 使用 Stripe CLI 在本地测试您的 Webhook 端点处理程序。
3. 为 Webhook 端点创建新的事件接收端。
4. 保护您的 Webhook 端点。

您可以注册并创建一个端点，用它同时处理几个不同的事件类型，也可以为特定事件设置单独的端点。

require 'json'

# Using Sinatra
post '/webhook' do
  payload = request.body.read
  event = nil

  begin
    event = Stripe::Event.construct_from(
      JSON.parse(payload, symbolize_names: true)
    )
  rescue JSON::ParserError => e
    # Invalid payload
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'payment_intent.succeeded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    # Then define and call a method to handle the successful payment intent.
    # handle_payment_intent_succeeded(payment_intent)
  when 'payment_method.attached'
    payment_method = event.data.object # contains a Stripe::PaymentMethod
    # Then define and call a method to handle the successful attachment of a PaymentMethod.
    # handle_payment_method_attached(payment_method)
  # ... handle other event types
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end

stripe listen --forward-to localhost:4242/webhook

stripe listen --events payment_intent.created,customer.created,payment_intent.succeeded,checkout.session.completed,payment_intent.payment_failed \
  --forward-to localhost:4242/webhook

stripe listen --load-from-webhooks-api --forward-to localhost:4242/webhook

Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)

stripe trigger payment_intent.succeeded
Running fixture for: payment_intent
Trigger succeeded! Check dashboard for event details.

注册您的端点

测试 Webhook 端点函数后，使用 Workbench 中的 API 或 Webhook 选项卡注册 Webhook 端点的可访问 URL，以便 Stripe 知道将事件传递到何处。您最多可以在 Stripe 上注册 16 个 Webhook 端点。注册的 Webhook 端点必须是可公开访问的 HTTPS URL。

Webhook URL 格式

注册 Webhook 端点时使用的 URL 格式：

https://<your-website>/<your-webhook-endpoint>

例如，如果您的域名是 https://mycompanysite.com，您的 Webhook 端点的路径为 @app.route('/stripe_webhooks', methods=['POST'])，那便指定 https://mycompanysite.com/stripe_webhooks 作为端点 URL。

为 Webhook 端点创建事件接收端

在管理平台中用 Workbench 创建事件接收端，或通过API 程序化地创建。最多可以在每个 Stripe 账户上注册 16 个事件接收端。

管理平台

API

在管理平台中创建新的 Webhook 端点：

1. 打开 Workbench 中的 Webhook 选项卡。
2. 点击创建事件目的地。
3. 选择从哪里接收事件。Stripe 支持两种类型的配置：您的账户和 Connect 子账户。选择账户，以从您自己的账户侦听事件。如果您创建了 Connect 应用程序，并且想要侦听来自您的 Connect 子账户的事件，请选择 Connect 子账户。

1. 为您想要使用的事件对象选择 API 版本。
2. 选择要发送到 Webhook 端点的事件类型。
3. 选择继续，然后选择 Webhook 端点作为接收端类型。
4. 点击继续，然后提供端点 URL 和 Webhook 的可选描述。

用 Webhook 选项卡注册新的 Webhook

注意

Workbench 将替换掉当前的开发人员管理平台。如果您仍在使用开发人员管理平台，请查看如何创建新的 Webhook 端点。

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

require 'stripe'
require 'sinatra'

# If you are testing your webhook locally with the Stripe CLI you
# can find the endpoint's secret by running `stripe listen`
# Otherwise, find your endpoint's secret in your webhook settings in
# the Developer Dashboard
endpoint_secret = 'whsec_...'

# Using the Sinatra framework
set :port, 4242

post '/my/webhook/url' do
  payload = request.body.read
  sig_header = request.env['HTTP_STRIPE_SIGNATURE']
  event = nil

  begin
    event = Stripe::Webhook.construct_event(
      payload, sig_header, endpoint_secret
    )
  rescue JSON::ParserError => e
    # Invalid payload
    puts "Error parsing payload: #{e.message}"
    status 400
    return
  rescue Stripe::SignatureVerificationError => e
    # Invalid signature
    puts "Error verifying webhook signature: #{e.message}"
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'payment_intent.succeeded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    puts 'PaymentIntent was successful!'
  when 'payment_method.attached'
    payment_method = event.data.object # contains a Stripe::PaymentMethod
    puts 'PaymentMethod was attached to a Customer!'
  # ... handle other event types
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end

调试 Webhook 集成

向 Webhook 端点发送事件时，可能会出现多种问题：

• Stripe 可能无法将事件发送到您的 Webhook 端点。
• 您的 Webhook 端点可能存在 SSL 问题。
• 您的网络连接时断时续。
• 您的 Webhook 端点没有接收到您期望接收的事件。

查看事件的发送情况

要查看事件传送情况，请在 Webhook 中选择 Webhook 端点，然后选择事件选项卡。

事件选项卡中提供了一个事件列表，以及它们是 Delivered、Pending 还是 Failed。点击某个事件可查看 Delivery attempts，其中包含以前尝试传送时的 HTTP 状态代码和未来待传送的时间。

在 Webhook 的事件选项卡中查看事件发送尝试。

修复 HTTP 状态代码

当一个事件显示状态代码 200 时，它表示已成功地发送到 Webhook 端点。您可能还会收到一个不同于 200 的状态代码。有关常见 HTTP 状态代码和推荐解决方案的列表，请查看下表。

事件的发送行为

本节旨在帮助您理解 Stripe 向 Webhook 端点发送事件时的不同行为。

自动重试

在真实模式下，我们会尽量连续三天一直尝试将事件发送到您的接收端，但尝试频率递减。在事件接收端的事件发送选项卡中查看下次重试的时间（如果适用）。我们在几个小时内重试了三次在沙盒中创建的事件发送操作。如果在我们重新尝试时您的接收端已被禁用或删除，我们将阻止您再次尝试该事件。但是，如果您在我们重试之前禁用并又重新启用事件接收端，则仍可以看到今后的重试尝试。

手动重试

There are two ways to manually retry events:

• In the Stripe Dashboard, click Resend when looking at a specific event. This works for up to 15 days after the event creation.
• With the Stripe CLI, run the stripe events resend <event_id> --webhook-endpoint=<endpoint_id> command. This works for up to 30 days after the event creation.

事件排序

Stripe 不保证事件按照生成的顺序发送。例如，创建订阅时可能会生成以下事件：

• customer.subscription.created
• invoice.created
• invoice.paid
• charge.created（如果有收款）

确保您的事件接收端不依赖于以特定顺序接收事件。准备好适当管理他们的提交操作。您还可以使用 API 来检索任何缺少的对象。例如，如果您先收到此事件，可以使用 invoice.paid 中的信息检索账单、收款和订阅对象。

API 版本控制

The API version in your account settings when the event occurs dictates the API version, and therefore the structure of an Event sent to your destination. For example, if your account is set to an older API version, such as 2015-02-16, and you change the API version for a specific request with versioning, the Event object generated and sent to your destination is still based on the 2015-02-16 API version. You can’t change Event objects after creation. For example, if you update a charge, the original charge event remains unchanged. As a result, subsequent updates to your account’s API version don’t retroactively alter existing Event objects. Retrieving an older Event by calling /v1/events using a newer API version also has no impact on the structure of the received event. You can set test event destinations to either your default API version or the latest API version. The Event sent to the destination is structured for the event destination’s specified version.

Webhook 用法最佳实践

查看这些最佳做法，时刻确保您的 Webhook 安全，并与您的集成应用良好运行。

处理重复事件

Webhook 端点有时可能会多次收到同一事件。您可以通过记录已处理的事件 ID，然后不处理已记录的事件来防止接收重复事件。

在某些情况下，会生成并发送两个单独的 Event 对象。要识别这些重复项，请使用 data.object 中对象 ID 和 event.type。

仅侦听集成所需的事件类型

将 Webhook 端点配置为仅接收集成所需的事件类型。侦听额外的事件（或所有事件）会给您的服务器带来过度的压力，因此不建议这样做。

您可以在管理平台或通过 API 更改事件（Webhook 端点收到的事件）。

异步处理事件

配置您的处理程序来处理带有异步队列的传入事件。如果选择同步处理事件，可能会遇到扩展性问题。Webhook 发送量的任何大峰值（例如，在所有订阅都续订的月初）都可能会使您的端点主机不堪重负。

异步队列可让您以系统支持的速度处理并发事件。

去除 Webhook 路由的 CSRF 保护

如果您正在使用 Rails、Django 或其他网络框架，则您的站点可能会自动检查每个 POST 请求是否包含一个_CSRF 令牌_。这是一个重要的安全功能，有助于保护您及您的用户免受跨站请求伪造 (cross-site request forgery, CSRF) 攻击。但是，这一安全措施也可能会阻止您的站点处理合法事件。如果是这样，则您可能需要从 CSRF 保护中去除 Webhook 路由。

class StripeController < ApplicationController
  # If your controller accepts requests other than Stripe webhooks,
  # you'll probably want to use `protect_from_forgery` to add CSRF
  # protection for your application. But don't forget to exempt
  # your webhook route!
  protect_from_forgery except: :webhook

  def webhook
    # Process webhook data in `params`
  end
end

通过 HTTPS 服务器接收事件

如果您为您的 Webhook 端点使用了 HTTPS URL（真实模式下要求），则 Stripe 会在发送您的 Webhook 数据之前先验证到您的服务器的连接是否安全。为此，您的服务器必须要正确配置，具有支持 HTTPS 的有效服务器证书。Stripe Webhook 仅支持 TLS 版本 v1.2 和 v1.3。

定期滚动端点签名密钥

用于验证事件来源于 Stripe 的私钥可在 Workbench 的 Webhook选项卡中中修改。为了保证它们的安全，建议您定期或者在怀疑私钥泄露时滚动（更改）私钥。

要滚动私钥：

1. 在 Workbench Webhook 选项卡中，点击您想要滚动私钥的每个端点。
2. 导航到溢出菜单 ()，然后点击滚动私钥。您可以选择立即使当前私钥过期，也可以延迟 24 小时后再让它过期，以便让自己有时间更新服务器上的验证码。这段时间内，端点会有多个密钥处于活动状态。Stripe 会为每个私钥生成一个签名，直到过期。

验证事件是否是从 Stripe 发送的

Stripe 会从一组固定的 IP 地址发送 Webhook 事件。仅信任来自这些 IP 地址的事件。

还要验证 Webhook 签名，以确认 Stripe 发送了接收的事件。Stripe 通过在每个事件的 Stripe-Signature 头中包含一个签名来对它发送到您的端点的 Webhook 事件进行签名。这样可表示事件是由 Stripe 发送的，而非第三方。可以用我们的官方库来验证签名，也可以用您自己的方案手动验证。

以下部分描述了 Webhook 签名的验证方式：

1. 检索您的端点的密钥。
2. 验证签名。

检索您的端点的密钥

使用 Workbench 并导航到 Webhook 选项卡以查看所有端点。选择要获取其私钥的端点，然后点击**“单击以显示”**。

Stripe 为每个端点生成一个唯一私钥。如果您为测试和真实 API 私钥使用相同的端点，则每个端点的私钥各不相同。此外，如果您使用多个端点，则必须要为您想用来验证签名的每个端点都获取一个私钥。有了这种设置，Stripe 便可开始对它发送到端点的每个 Webhook 进行签名。

防止重放攻击

重放攻击 (Replay Attack)是攻击者截获有效的有效载荷及其签名，然后再重新传输。为了减轻这类攻击，Stripe 在 Stripe-Signature 头内包含了时间戳。因为此时间戳是已签名的有效载荷的一部分，因此它也由签名验证，所以攻击者在不使签名无效的情况下不能更改时间戳。如果签名有效，但时间戳太旧，则您可以让您的应用程序拒绝有效载荷。

我们的库在时间戳和当前时间之间有 5 分钟的默认容差。您可以通过在验证签名时提供附加参数来更改此容差。使用网络时间协议（Network Time Protocol，简称NTP），确保您的服务器时钟的准确性，并与 Stripe 的服务器时间同步。

每当向您的端点发送事件时，Stripe 都会生成时间戳和签名。如果 Stripe 重试一个事件（例如，您的端点之前回复了一个非 2xx 的状态码），则我们会为新的发送尝试生成新的签名和时间戳。

快速返回 2xx 响应

您的端点必须要快速返回一个成功的状态码 (2xx)，然后才能执行任何可能导致超时的复杂逻辑。例如，您必须返回一个 200 响应，然后才能在您的会计系统中将客户的账单更新为已支付。