---
title: "设置 webhook 集成"
description: "在 Adapty 中设置 webhook 集成以实现事件跟踪自动化。"
---

Adapty 的 [webhook 集成](webhook) 包含以下步骤：

  <img src="/assets/shared/img/webhook-setup.webp"
  style={{
    border: '1px solid #727272', /* border width and color */
    width: '300px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

<p> </p>

1. **您设置端点：**
   1. 确保您的服务器能够处理 Adapty 发送的、**Content-Type** 请求头设置为 `application/json` 的请求。
   2. 配置您的服务器以接收 Adapty 的验证请求，并以任意 `2xx` 状态码和 JSON 正文进行响应。
   3. 连接验证通过后，[处理订阅事件](#subscription-events)。
2. **您在 [Adapty 看板](#configure-webhook-integration-in-the-adapty-dashboard)中配置并启用 webhook 集成**。您还可以[将 Adapty 事件映射到自定义事件名称](#configure-webhook-integration-in-the-adapty-dashboard)。我们建议在切换到生产环境之前先在**沙盒环境**中进行测试。
3. **Adapty 向您的服务器发送验证请求。**
4. **您的服务器**以 `2XX` 状态码和 JSON 正文进行**响应**。
5. **Adapty 收到有效响应后，开始发送订阅事件。**

## 设置您的服务器以处理 Adapty 请求 \{#set-up-your-server-to-process-adapty-requests\}

Adapty 将向您的 webhook 端点发送 2 种类型的请求：

1. [验证请求](#verification-request)：用于验证连接是否正确建立的初始请求。此请求不包含任何事件，将在您点击 Adapty 看板中 Webhook 集成页面的 **Save** 按钮时立即发送。为确认您的端点成功收到验证请求，您的端点应返回验证响应。
2. [订阅事件](#subscription-events)：Adapty 服务器在每次创建事件时发送的标准请求。您的服务器无需返回任何特定响应，Adapty 服务器只需收到标准的 200 状态码 HTTP 响应即表示成功接收消息。

### 验证请求 \{#verification-request\}

在您于 Adapty 看板中启用 webhook 集成后，Adapty 将发送一个以空 JSON 对象 `{}` 为正文的 POST 验证请求。

请将您的端点的 **Content-Type 请求头**设置为 `application/json`，即您服务器的端点应期望接收的 webhook 请求的负载格式为 JSON。

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

```json title="Json"
{}
```

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

### 订阅事件 \{#subscription-events\}

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

## 在 Adapty 看板中配置 webhook 集成 \{#configure-webhook-integration-in-the-adapty-dashboard\}

在 Adapty 中，您可以为生产事件和来自 Apple、Stripe 沙盒环境或 Google 测试账户的测试事件分别配置独立的流程。

对于生产事件，请使用 **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](https://app.adapty.io/integrations/customwebhook)。

  <img src="/assets/shared/img/webhook_integration.webp"
  style={{
    border: '1px solid #727272', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

2. 打开开关以启动集成。
4. 填写集成字段：

    | 字段 | 描述 |
    | ------------------------------------------------------ | ------------------------------------------------------------ |
    | **Production endpoint URL** | Adapty 用于向生产环境发送 HTTP POST 请求的 URL。 |
    | **Authorization header value for production endpoint** | <p>您的服务器将用于对 Adapty 生产环境请求进行身份验证的请求头。请注意，我们将使用此字段中指定的值原样作为 `Authorization` 请求头，不做任何修改或添加。</p><p></p><p>虽然不是强制性的，但强烈建议设置以增强安全性。</p> |

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

    | 测试字段 | 描述 |
    | --------------------------------------------------- | ------------------------------------------------------------ |
    | **Sandbox endpoint URL** | Adapty 用于向沙盒环境发送 HTTP POST 请求的 URL。 |
    | **Authorization header value for sandbox endpoint** | <p>您的服务器将用于对 Adapty 沙盒环境测试请求进行身份验证的请求头。请注意，我们将使用此字段中指定的值原样作为 `Authorization` 请求头，不做任何修改或添加。</p><p></p><p>虽然不是强制性的，但强烈建议设置以增强安全性。</p> |

4. （可选）选择您希望接收的事件并映射其名称。请查看我们的[事件流](event-flows)，了解不同情况下触发的事件。

   如果您的事件 ID 与 Adapty 中使用的不同，请保留您系统中的 ID，并在 [Integrations -> Webhooks](https://app.adapty.io/integrations/customwebhook) 页面的 **Events names** 部分，将默认的 Adapty 事件 ID 替换为您自己的 ID。

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

  <img src="/assets/shared/img/86942b8-event_names_renaming.webp"
  style={{
    border: '1px solid #727272', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

5. 其他字段和选项不是必填项，请根据需要使用：

    | 设置 | 描述 |
    | :--------------------------------- | :----------------------------------------------------------- |
    | **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` 字段中。有关更多信息，请参阅[事件字段](webhook-event-types-and-fields#event-fields)。 |
    | **Send attribution** | 启用此选项以在 `attributions` 字段中包含归因信息（例如 AppsFlyer 数据）。详情请参阅[归因数据](webhook-event-types-and-fields#attributions)部分。 |
    | **Send Play Store purchase token** | 启用此选项以接收购买重新验证所需的 Play Store 令牌（如有需要）。启用后，事件中将添加 `play_store_purchase_token` 参数。有关其内容的详细信息，请参阅 [Play Store 购买令牌](webhook-event-types-and-fields#play-store-purchase-token)部分。 |

6. 请记得点击 **Save** 按钮以确认更改。

点击 **Save** 按钮的同时，Adapty 将发送验证请求并等待您服务器的验证响应。

### 选择要发送的事件并映射事件名称 \{#choose-events-to-send-and-map-event-names\}

通过启用事件旁边的开关来选择您希望在服务器中接收的事件。如果您的事件名称与 Adapty 中使用的不同，且需要保留您自己的名称，您可以在 [Integrations -> Webhooks](https://app.adapty.io/integrations/customwebhook) 页面的 **Events names** 部分，将默认的 Adapty 事件名称替换为您自己的名称来设置映射。

  <img src="/assets/shared/img/86942b8-event_names_renaming.webp"
  style={{
    border: '1px solid #727272', /* border width and color */
    width: '700px', /* image width */
    display: 'block', /* for alignment */
    margin: '0 auto' /* center alignment */
  }}
/>

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

## 处理 webhook 事件 \{#handle-webhook-events\}

Webhook 通常在事件发生后 5 到 60 秒内送达。但取消事件可能在用户取消订阅后最多需要 2 小时才能送达。
如果您服务器的响应状态码不在 200-404 范围内，Adapty 将在 24 小时内以指数退避方式最多重试发送事件 9 次。我们建议您将 webhook 设置为在响应之前仅对来自 Adapty 的事件正文进行基本验证。如果您的服务器无法处理事件且不希望 Adapty 重试，请使用 200-404 范围内的状态码。此外，请异步处理任何耗时任务，并快速响应 Adapty。如果 Adapty 在 10 秒内未收到响应，将视本次尝试为失败并进行重试。