设置 Webhook 集成

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

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

设置服务器以处理 Adapty 请求

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

验证请求：用于验证连接是否正确建立的初始请求。该请求不包含任何事件，将在您点击 Adapty 看板 Webhook 集成中的 Save 按钮时立即发送。为确认您的端点成功接收到验证请求，您的端点应返回验证响应。
订阅事件：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 测试账号）分别配置独立的流程。

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 集成：

在 Adapty 看板中打开 Integrations -> Webhook。

打开开关以启动集成。

填写集成字段：

字段描述

Production endpoint URL Adapty 用于在生产环境中发送事件 HTTP POST 请求的 URL。

字段	描述
Production endpoint URL	Adapty 用于在生产环境中发送事件 HTTP POST 请求的 URL。
Authorization header value for production endpoint	您的服务器用于验证来自 Adapty 的生产环境请求的请求头。请注意，我们将使用此字段中指定的值作为 `Authorization` 请求头，不会进行任何修改或添加。虽然不是必填项，但强烈建议配置以提升安全性。

Authorization header value for production endpoint

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

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

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

测试字段说明

Sandbox endpoint URL Adapty 在沙盒环境中发送事件 HTTP POST 请求时所使用的 URL。

测试字段	说明
Sandbox endpoint URL	Adapty 在沙盒环境中发送事件 HTTP POST 请求时所使用的 URL。
Authorization header value for sandbox endpoint	您的服务器在沙盒环境测试期间，用于验证 Adapty 请求的请求头。请注意，我们会将该字段中指定的值原样作为 `Authorization` 请求头使用，不做任何修改或补充。虽然非强制要求，但强烈建议配置此项以提升安全性。

Authorization header value for sandbox endpoint

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

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

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

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

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

其他字段和选项并非必填，请按需使用：

设置	描述
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 购买令牌部分。

记得点击 Save 按钮确认更改。

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

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

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

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

处理 Webhook 事件

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

如果您服务器的响应状态码不在 200-404 范围内，Adapty 会以指数退避方式重试。首次重试大约在初次失败后 1 分钟发生，此后每次间隔翻倍——最多重试 9 次，分布在 24 小时内。建议您将 Webhook 配置为仅对 Adapty 发来的事件体做基本校验后再响应。如果您的服务器无法处理该事件且不希望 Adapty 重试，请使用 200-404 范围内的状态码。此外，请将耗时任务改为异步处理，并尽快向 Adapty 返回响应。若 Adapty 在 10 秒内未收到响应，则视为本次尝试失败并将进行重试。