English 中文TürkçeРусскийFrançaisTiếng ViệtEspañol日本語

设置 Webhook 集成

Adapty Webhook 集成 由以下步骤组成：

webhook-setup.webp

  1. 您设置好端点：
    1. 确保您的服务器能够处理 Adapty 请求，并将 Content-Type 请求头设置为 application/json。
    2. 配置您的服务器以接收 Adapty 的验证请求，并返回任意 2xx 状态码和 JSON 响应体。
    3. 连接验证通过后，处理订阅事件。
  2. 您在 Adapty 看板中配置并启用 Webhook 集成。 您也可以将 Adapty 事件映射到自定义事件名称。建议先在 Sandbox environment 中测试，再切换到生产环境。
  3. Adapty 向您的服务器发送验证请求。
  4. 您的服务器返回 2XX 状态码和 JSON 响应体。
  5. Adapty 收到有效响应后，即开始发送订阅事件。

设置服务器以处理 Adapty 请求

Adapty 会向你的 webhook 端点发送 2 种类型的请求：

  1. 验证请求：用于验证连接是否正确建立的初始请求。该请求不包含任何事件，将在您点击 Adapty 看板 Webhook 集成中的 Save 按钮时立即发送。为确认您的端点成功接收到验证请求，您的端点应返回验证响应。
  2. 订阅事件：Adapty 服务器在每次创建事件时发送的标准请求。您的服务器无需返回任何特定响应，Adapty 服务器唯一需要的是在成功接收消息后收到标准的 HTTP 200 响应码。

验证请求

在 Adapty 看板中启用 webhook 集成后，Adapty 会发送一个 POST 验证请求，请求体为空 JSON 对象 {}。

请将你的端点配置为使用 Content-Type header application/json，即你的服务器端点应接受以 JSON 格式传入的 webhook 请求。

你的服务器必须返回 2xx 状态码，并发送任意有效的 JSON 响应，例如：

{}

一旦 Adapty 收到格式正确且状态码为 2xx 的验证响应，您的 Adapty webhook 集成即配置完成。

订阅事件

订阅事件在发送时，Content-Type 请求头设置为 application/json，并以 JSON 格式包含事件数据。有关可能的事件类型和请求结构，请参阅 Webhook 事件类型与字段。

在 Adapty 看板中配置 Webhook 集成

在 Adapty 中，你可以为正式环境事件和测试事件（来自 Apple 或 Stripe 沙盒环境，或 Google 测试账号）分别配置独立的流程。

Tip

Adapty 每个环境（正式环境和沙盒环境）仅支持一个 Webhook URL。如需将事件推送至多个服务，请将 Webhook 指向你自己的后端，再由后端进行分发。

对于生产环境事件，请使用 Production endpoint URL 字段填写回调发送的目标 URL。同时配置 Authorization header value for production endpoint 字段——该字段用于您的服务器验证 Adapty 事件。请注意，我们会将 Authorization header value for production endpoint 字段中填写的值原样作为 Authorization 请求头发送，不做任何修改或添加。

对于测试事件，请相应地使用 Sandbox endpoint URL 和 Authorization header value for sandbox endpoint 字段。

要设置 webhook 集成：

  1. 在 Adapty 看板中打开 Integrations -> Webhook。
webhook_integration.webp

  1. 打开开关以启动集成。

  2. 填写集成字段：

    字段描述
    Production endpoint URLAdapty 用于在生产环境中发送事件 HTTP POST 请求的 URL。
    Authorization header value for production endpoint

    您的服务器用于验证来自 Adapty 的生产环境请求的请求头。请注意，我们将使用此字段中指定的值作为 Authorization 请求头，不会进行任何修改或添加。

    虽然不是必填项，但强烈建议配置以提升安全性。

此外，为了满足您在沙盒环境中的测试需求，还提供了另外两个字段：

测试字段说明
Sandbox endpoint URLAdapty 在沙盒环境中发送事件 HTTP POST 请求时所使用的 URL。
Authorization header value for sandbox endpoint

您的服务器在沙盒环境测试期间，用于验证 Adapty 请求的请求头。请注意，我们会将该字段中指定的值原样作为 Authorization 请求头使用，不做任何修改或补充。

虽然非强制要求，但强烈建议配置此项以提升安全性。

  1. （可选）选择您希望接收的事件并映射其名称。请查阅事件流程，了解在不同情况下会触发哪些事件。

    如果您系统中的事件 ID 与 Adapty 中使用的 ID 不同，请保留您系统中的 ID，并在 Integrations -> Webhooks 页面的 Events names 部分，将 Adapty 默认事件 ID 替换为您自己的 ID。

事件 ID 可以是任意字符串；只需确保 Webhook 处理服务器中的事件 ID 与您在 Adapty 看板中输入的一致。已启用的事件不能将事件 ID 留空。

86942b8-event_names_renaming.webp
  1. 其他字段和选项并非必填，请按需使用：
设置描述
Send Trial Price启用后，Adapty 将在 Trial Started 事件的 price_local 和 price_usd 字段中包含订阅价格。
Exclude Historical Events选择排除用户在安装含 Adapty SDK 的应用之前发生的事件。这可以防止事件重复，并确保报告准确。例如，若用户于 1 月 10 日激活了月度订阅，并于 3 月 6 日更新了含 Adapty SDK 的应用，则 Adapty 将忽略 3 月 6 日之前的事件，并保留此后的事件。
Send user attributes启用此选项以发送用户特定属性，例如语言偏好。这些属性将显示在 user_attributes 字段中。详见事件字段。
Send attribution启用此选项以在 attributions 字段中包含归因信息（例如 AppsFlyer 数据）。详见归因数据部分。
Send Play Store purchase token启用此选项以接收购买重新验证所需的 Play Store 令牌（如有需要）。启用后将在事件中添加 play_store_purchase_token 参数。有关其内容的详细信息，请参阅 Play Store 购买令牌部分。
  1. 记得点击 Save 按钮确认更改。

点击 Save 按钮后，Adapty 将立即发送验证请求，并等待您的服务器返回验证响应。

选择要发送的事件并映射事件名称

通过启用事件旁边的开关，选择您希望服务器接收的事件。如果您的事件名称与 Adapty 中使用的名称不同，且需要保留自定义名称，可以在 Integrations -> Webhooks 页面的 Events names 部分，将默认的 Adapty 事件名称替换为您自己的名称，从而完成映射配置。

86942b8-event_names_renaming.webp

事件名称可以是任意字符串。已启用的事件对应的字段不能留空。如果您不小心删除了 Adapty 事件名称，可以随时从发送至第三方集成的事件文档中复制。

处理 webhook 事件

Webhook 通常在事件发生后 5 到 60 秒内送达。但取消订阅事件可能在用户取消后最长 2 小时才会送达。

Adapty 的 webhook 采用至少一次投递机制：每个事件至少会有一次投递尝试，失败时 Adapty 会重试而不是直接丢弃。如果您服务器的响应状态码不在 200-404 范围内，Adapty 会以指数退避策略重试投递。第一次重试大约在初次失败后 1 分钟发生，此后每次间隔翻倍——最多重试 9 次，分布在 24 小时内。建议您将 webhook 设置为仅对 Adapty 发来的事件主体做基本校验，然后再响应。如果您的服务器无法处理该事件且不希望 Adapty 重试，请使用 200-404 范围内的状态码。此外，将耗时任务异步处理，并尽快响应 Adapty。如果 Adapty 在 10 秒内未收到响应，则视为本次尝试失败并会重试。

事件不保证按顺序到达——请参阅事件字段了解如何自行对事件进行排序和去重。

Note

除上述计划外，重试还受到两项限制。如果您的端点在 24 小时内没有成功投递，Adapty 将停止重试其失败事件，直到再次成功投递为止。此外，事件在创建后 24 小时内未能投递，则不再重试。长时间中断期间失败的事件不会自动重新发送——如需重新发送，请联系 Adapty 支持团队。

暂停推送（多次失败后）

当发送到您端点的最近几次投递均失败时，Adapty 会暂停该应用的 Webhook 投递。此处的失败条件与重试机制相同：响应状态码不在 200–404 范围内、连接错误或 10 秒内无响应均视为失败。投递暂停期间，Adapty 不会向您的端点发送新事件，也不会在之后重试这些事件。这些事件会显示 Sending failed 状态，即使您的服务器从未收到过任何请求。冷却期结束后，Adapty 会发送下一个事件以测试端点是否恢复正常。若该次投递成功，正常投递将自动恢复；若再次失败，投递将再次暂停，且冷却时间将延长。

当您点击 Save 时，Adapty 发送的验证请求不经过此投递流程，因此即使投递暂停，验证也能成功。

要保持投递正常运行，请对每个事件都返回 2xx 状态码，包括您的服务器暂时无法匹配到用户的事件，并在您这一侧进行处理。