Webhook 事件类型与字段

Adapty 会在订阅事件发生时发送 webhook。本节定义了这些事件类型以及每个 webhook 中包含的数据。

事件名称	描述
subscription_started	当用户激活不含试用期的付费订阅时触发，即立即计费。
subscription_renewed	当订阅续期并向用户收费时发生。此事件从第二次计费开始触发，无论是试用订阅还是非试用订阅。
subscription_renewal_cancelled	用户已关闭订阅自动续期。用户在付费订阅期结束前仍可访问高级功能。
subscription_renewal_reactivated	当用户重新激活订阅自动续期时触发。
subscription_expired	当订阅取消后完全结束时触发。例如，若用户在 12 月 12 日取消订阅，但订阅在 12 月 31 日前仍处于活跃状态，则该事件在 12 月 31 日订阅到期时记录。
subscription_paused	当用户激活订阅暂停时发生（仅限 Android）。
subscription_deferred	当订阅购买被延迟时触发，允许用户在延迟付款的同时继续访问高级功能。此功能通过 Google Play Developer API 提供，可用于免费试用或为面临经济困难的用户提供便利。
non_subscription_purchase	任何非订阅购买，例如永久授权或消耗型商品（如游戏内金币）。
trial_started	当用户激活试用订阅时触发。
trial_converted	当试用期结束并向用户收费（首次购买）时发生。例如，若用户的试用期至 1 月 14 日，但在 1 月 7 日被收费，则该事件在 1 月 7 日记录。
trial_renewal_cancelled	用户在试用期间关闭了订阅自动续期。用户在试用期结束前仍可访问高级功能，但不会被收费或开始订阅。
trial_renewal_reactivated	当用户在试用期间重新激活订阅自动续期时发生。
trial_expired	当试用期结束且未转化为订阅时触发。
entered_grace_period	当付款尝试失败且用户进入宽限期（如已启用）时发生。用户在此期间仍保留高级访问权限。
billing_issue_detected	当计费尝试过程中发生计费问题时触发（例如，银行卡余额不足）。
subscription_refunded	当订阅被退款时触发（例如，由 Apple Support 处理）。
non_subscription_purchase_refunded	当非订阅购买被退款时触发。
access_level_updated	当用户的访问等级更新时发生。

Webhook 事件类型

您可以将所有事件类型发送至您的 Webhook，也可以仅选择其中部分类型。您可以参阅我们的事件流，了解预期接收的数据类型以及如何围绕其构建业务逻辑。在设置 Webhook 集成时，您可以禁用不需要的事件类型。在那里，如有需要，您还可以将 Adapty 默认的事件 ID 替换为您自己的 ID。

事件名称	描述
subscription_started	当用户激活不含试用期的付费订阅时触发，即立即计费。
subscription_renewed	当订阅续期并向用户收费时发生。此事件从第二次计费开始触发，无论是试用订阅还是非试用订阅。
subscription_renewal_cancelled	用户已关闭订阅自动续期。用户在付费订阅期结束前仍可访问高级功能。
subscription_renewal_reactivated	当用户重新激活订阅自动续期时触发。
subscription_expired	当订阅取消后完全结束时触发。例如，若用户在 12 月 12 日取消订阅，但订阅在 12 月 31 日前仍处于活跃状态，则该事件在 12 月 31 日订阅到期时记录。
subscription_paused	当用户激活订阅暂停时发生（仅限 Android）。
subscription_deferred	当订阅购买被延迟时触发，允许用户在延迟付款的同时继续访问高级功能。此功能通过 Google Play Developer API 提供，可用于免费试用或为面临经济困难的用户提供便利。
non_subscription_purchase	任何非订阅购买，例如永久授权或消耗型商品（如游戏内金币）。
trial_started	当用户激活试用订阅时触发。
trial_converted	当试用期结束并向用户收费（首次购买）时发生。例如，若用户的试用期至 1 月 14 日，但在 1 月 7 日被收费，则该事件在 1 月 7 日记录。
trial_renewal_cancelled	用户在试用期间关闭了订阅自动续期。用户在试用期结束前仍可访问高级功能，但不会被收费或开始订阅。
trial_renewal_reactivated	当用户在试用期间重新激活订阅自动续期时发生。
trial_expired	当试用期结束且未转化为订阅时触发。
entered_grace_period	当付款尝试失败且用户进入宽限期（如已启用）时发生。用户在此期间仍保留高级访问权限。
billing_issue_detected	当计费尝试过程中发生计费问题时触发（例如，银行卡余额不足）。
subscription_refunded	当订阅被退款时触发（例如，由 Apple Support 处理）。
non_subscription_purchase_refunded	当非订阅购买被退款时触发。
access_level_updated	当用户的访问等级更新时发生。

Webhook 事件结构

Adapty 只会向您发送您在 Integrations -> Webhooks 页面的 Events names 部分中选择的事件。

Webhook 事件以 JSON 格式序列化。向您服务器发送的 POST 请求正文将包含序列化后的事件，并封装在以下结构中。所有事件遵循相同的结构，但其字段会根据事件类型、商店以及您的具体配置有所不同。用户属性是您设置的自定义用户属性，因此它们包含您已配置的内容。所有事件类型的归因数据字段也相同，但归因列表将取决于您在移动应用中使用的归因来源。以下是一个事件示例：

{
  "profile_id": "00000000-0000-0000-0000-000000000000",
  "customer_user_id": "UserIdInYourSystem",
  "idfv": "00000000-0000-0000-0000-000000000000",
  "idfa": "00000000-0000-0000-0000-000000000000",
  "advertising_id": "00000000-0000-0000-0000-000000000000",
  "profile_install_datetime": "2000-01-31T00:00:00.000000+0000",
  "user_agent": "ExampleUserAgent/1.0 (Device; OS Version) Browser/Engine",
  "email": "[email protected]",
  "event_type": "subscription_started",
  "event_datetime": "2000-01-31T00:00:00.000000+0000",
  "event_properties": {
    "store": "play_store",
    "currency": "USD",
    "price_usd": 4.99,
    "profile_id": "00000000-0000-0000-0000-000000000000",
    "cohort_name": "All Users",
    "environment": "Production",
    "price_local": 4.99,
    "base_plan_id": "b1",
    "developer_id": "onboarding_placement",
    "ab_test_name": "onboarding_ab_test",
    "ab_test_revision": 1,
    "paywall_name": "UsedPaywall",
    "proceeds_usd": 4.2315,
    "variation_id": "00000000-0000-0000-0000-000000000000",
    "purchase_date": "2024-11-15T10:45:36.181000+0000",
    "store_country": "AR",
    "event_datetime": "2000-01-31T00:00:00.000000+0000",
    "proceeds_local": 4.2415,
    "tax_amount_usd": 0,
    "transaction_id": "0000000000000000",
    "net_revenue_usd": 4.2415,
    "profile_country": "AR",
    "paywall_revision": "1",
    "profile_event_id": "00000000-0000-0000-0000-000000000000",
    "tax_amount_local": 0,
    "net_revenue_local": 4.2415,
    "vendor_product_id": "onemonth_no_trial",
    "profile_ip_address": "10.10.1.1",
    "consecutive_payments": 1,
    "rate_after_first_year": false,
    "original_purchase_date": "2000-01-31T00:00:00.000000+0000",
    "original_transaction_id": "0000000000000000",
    "subscription_expires_at": "2000-01-31T00:00:00.000000+0000",
    "profile_has_access_level": true,
    "profile_total_revenue_usd": 4.99,
    "promotional_offer_id": null,
    "store_offer_category": null,
    "store_offer_discount_type": null
  },
  "event_api_version": 1,
  "profiles_sharing_access_level": [{"profile_id": "00000000-0000-0000-0000-000000000000", "customer_user_id": "UserIdInYourSystem"}],
   "attributions": {
    "appsflyer": {
      "ad_set": "Keywords 1.12",
      "status": "non_organic",
      "channel": "Google Ads",
      "ad_group": null,
      "campaign": "Social media influencers - Rest of the world",
      "creative": null,
      "created_at": "2000-01-31T00:00:00.000000+0000"
    }
  },
  "user_attributes": {"Favourite_color": "Violet", "Pet_name": "Fluffy"},
  "integration_ids": {"firebase_app_instance_id": "val1", "branch_id": "val2", "one_signal_player_id": "val3"},
  "play_store_purchase_token": {
    "product_id": "product_123",
    "purchase_token": "token_abc_123",
    "is_subscription": true
  }
}

事件字段

事件参数对所有事件类型均相同。

字段	类型	描述
advertising_id	UUID	广告 ID（仅限 Android）。
attributions	JSON	归因数据。如果在 Webhook 设置中启用了 Send Attribution，则包含此字段。
customer_user_id	String	您的应用中的用户 ID（UUID、电子邮件或其他 ID），前提是您在识别用户时在应用代码中设置了此项。如果您未在应用代码中识别用户，或该特定用户是匿名用户（未登录），则此字段为 `null`。
email	String	用户的电子邮件，前提是您使用 Adapty SDK 中的 `updateProfile` 方法，或通过服务端 API 创建/更新用户画像时设置了此项。如果您未向 SDK 或 API 方法传递 `email` 值，则此字段为 `null`。
event_api_version	Integer	Adapty API 版本（当前版本：`1`）。
event_datetime	ISO 8601	事件时间戳，格式为 ISO 8601（例如：`2020-07-10T15:00:00.000000+0000`）。
event_properties	JSON	事件属性。
event_type	String	Adapty 格式的事件名称。完整列表请参见 Webhook 事件类型。
idfa	UUID	广告 ID（仅限 Apple）。即 Adapty 看板中用户画像里的 IDFA。由于追踪限制、儿童模式或隐私设置，该值可能为 `null`。
idfv	UUID	供应商标识符（IDFV），每个开发者唯一。即 Adapty 看板中用户画像里的 IDFV。
integration_ids	JSON	用户集成 ID，前提是您使用 Adapty SDK 中的 `setIntegrationIdentifier` 方法，或通过服务端 API 创建/更新用户画像时设置了此项。如果不可用或集成已禁用，则为 `null`。
play_store_purchase_token	JSON	Play Store 购买令牌，如果在 Webhook 设置中启用了 Send Play Store purchase token，则包含此字段。
profile_id	UUID	Adapty 为每个用户画像自动生成的用户画像 ID。如果您未识别用户或允许在登录前购买，同一个 Apple/Google ID 可能与不同的用户画像 ID 关联。了解 Adapty 处理父/继承用户画像的方式。
profile_install_datetime	ISO 8601	安装时间戳，格式为 ISO 8601（例如：`2020-07-10T15:00:00.000000+0000`）。
profiles_sharing_access_level	JSON	共享访问等级的用户列表（不含当前用户画像）。如果您的应用启用了访问等级共享，该列表包含使用相同 Apple/Google ID 的其他用户画像。格式： profile_id：（UUID）Adapty ID customer_user_id：（String）客户用户 ID（如已提供）
user_agent	String	设备浏览器的 User-Agent。
user_attributes	JSON	您可以设置的自定义数据，用于丰富用户画像中的应用特定信息。通常用于追踪用户偏好（例如主题、语言）或行为标记（完成用户引导、功能使用情况）。格式为键值对，其中键为字符串，值可以是字符串或数字（例如：`{"Favourite_color": "Violet", "Pet_name": "Fluffy"}`）。您可以在 Adapty 看板中为单个用户画像手动设置自定义属性，也可以使用 Adapty SDK 中的 `updateProfile` 方法以编程方式设置，或通过服务端 API 在创建/更新用户画像时设置。如果在 Webhook 设置中启用了 Send User Attributes，则包含此字段。虽然在移动应用代码中自定义属性值可以设置为浮点数或字符串，但通过服务端 API 或历史数据导入接收到的属性可能采用不同格式。在这种情况下，布尔值和整数值将被转换为浮点数。

归因

要发送归因数据，请在 Integrations -> Webhooks 页面中启用 Send Attribution 选项。如果您已启用发送归因数据，并且已配置归因集成，则以下数据将随每个来源的事件一起发送。相同的归因数据会发送给所有事件类型。

{
  "attributions": {
    "appsflyer": {
      "ad_set": "sample_ad_set_123",
      "status": "non_organic",
      "channel": "sample_channel",
      "ad_group": "sample_ad_group_456",
      "campaign": "sample_ios_campaign",
      "creative": "sample_creative_789",
      "created_at": "2000-01-31T00:00:00.000000+0000",
      "network_user_id": "0000000000000-0000000"
    }
  }
}

字段名称	字段类型	描述
ad_set	String	归因广告组。
status	String	可以是 `organic`、`non_organic,` 或 `unknown`。
channel	String	营销渠道名称。
ad_group	String	归因广告分组。
campaign	String	营销活动名称。
creative	String	归因创意关键词。
created_at	ISO 8601 date	归因记录的创建日期和时间。
network_user_id	String	归因来源分配给用户的 ID。

集成 ID

以下集成 ID 目前在事件中使用：

adjust_device_id
airbridge_device_id
amplitude_device_id
amplitude_user_id
appmetrica_device_id
appmetrica_profile_id
appsflyer_id
branch_id
facebook_anonymous_id
firebase_app_instance_id
mixpanel_user_id
pushwoosh_hwid
one_signal_player_id
one_signal_subscription_id
tenjin_analytics_installation_id
posthog_distinct_user_id

Play Store 购买令牌

此字段包含在必要时重新验证购买所需的所有数据。仅当在 Webhook 集成设置中启用了 Send Play Store purchase token 选项时才会发送。

字段	类型	描述
product_id	String	在 Play Store 中购买的产品（SKU）的唯一标识符。
purchase_token	String	由 Google Play 生成的令牌，用于唯一标识此购买交易。
is_subscription	Boolean	表示所购买的产品是否为订阅（`true`）或一次性购买（`false`）。

事件属性

事件属性可能因事件类型而异，甚至同一类型的不同事件之间也可能存在差异。例如，来自 App Store 的事件不会包含 Android 特有的属性，如 base_plan_id。

访问等级已更新事件具有独特的属性，因此我们为其单独设立了一个章节。同样，我们也将额外税费与收入事件属性单独列出，因为它们仅适用于某些特定的事件类型。

适用于大多数事件类型

大多数事件类型的事件属性是一致的（访问等级已更新 事件除外，该事件在其专属章节中进行说明）。下表全面列出了各属性，并标注了它们所属的特定事件。

字段	类型	描述
ab_test_name	String	交易来源的 Adapty A/B 测试名称。
ab_test_revision	Integer	交易来源的 A/B 测试版本号。
base_plan_id	String	Google Play 商店中的基础方案 ID，或 Stripe 中的价格 ID。
cancellation_reason	String	可能的取消原因：`voluntarily_cancelled`、`billing_error`、`price_increase`、`product_was_not_available`、`refund`、`cancelled_by_developer`、`new_subscription_replace`、`upgraded`、`unknown`、`adapty_revoked`。出现在以下事件类型中： `subscription_cancelled`、`subscription_refunded` 和 `trial_cancelled`。
cohort_name	String	决定向用户展示哪个付费墙的目标受众名称。
consecutive_payments	Integer	用户连续订阅的周期数，不含中断。包含当前周期。
currency	String	本地货币。
developer_id	String	交易来源的版位 ID。
environment	String	可能的值为 `Sandbox` 或 `Production`。
event_datetime	ISO 8601 date	事件的日期和时间。与事件根级别的值相同。
original_purchase_date	ISO 8601 date	对于周期性订阅，原始购买是链中的第一笔交易，其 ID 称为原始交易 ID，用于关联续订链；后续交易是其延伸。原始购买日期是第一笔交易的日期和时间。
original_transaction_id	String	对于周期性订阅，这是关联续订链的原始交易 ID。原始交易是链中的第一笔；后续交易是其延伸。如果没有延伸交易，`original_transaction_id` 与 store_transaction_id 相同。
paywall_name	String	交易来源的付费墙名称。
paywall_revision	String	交易来源的付费墙版本号，默认值为 1。
price_local	Float	扣除 Apple/Google 分成前的本地货币产品价格。
price_usd	Float	扣除 Apple/Google 分成前的美元产品价格。
profile_country	String	由 Adapty 根据用户画像 IP 确定。
profile_event_id	UUID	可用于去重的唯一事件 ID。
profile_has_access_level	Boolean	布尔值，表示用户画像是否拥有有效的访问等级。
profile_id	UUID	Adapty 生成的用户画像 ID。与事件根级别的值相同。
profile_ip_address	String	用户画像 IP（可以是 IPv4 或 IPv6，优先使用 IPv4）。如果在应用设置中禁用了 Collect users’ IP addresses，则为 `null`。
profile_total_revenue_usd	Float	用户画像的总收入（已扣除退款）。
promotional_offer_id	String	所使用的促销活动的 Adapty ID。该 ID 由您在看板中创建优惠时设置。
purchase_date	ISO 8601 date	产品购买的日期和时间。
rate_after_first_year	Boolean	布尔值，表示该订阅在持续续订满一年后是否符合降低佣金比例（通常为 15%）的条件。佣金比例因计划资格和国家/地区而异。详情请参阅商店佣金与税费。
store	String	产品购买所在的商店。标准值：app_store、play_store、stripe、paddle。如果您使用服务端 API 设置了自定义商店交易，则使用 store 参数中的值。
store_country	String	应用商店发送给我们的国家/地区。
store_offer_category	String	应用的优惠类别。可能的值为 `introductory`、`promotional`、`winback`。
store_offer_discount_type	String	应用的优惠类型。可能的值为 `free_trial`、`pay_as_you_go` 和 `pay_up_front`。
subscription_expires_at	ISO 8601 date	订阅的到期日期，通常为未来某个时间。
transaction_id	String	交易的唯一标识符。
trial_duration	String	试用期时长（以天为单位）。格式为” days”，例如”7 days”。仅出现在与试用相关的事件类型中：`trial_started`、`trial_converted`、`trial_cancelled`。
variation_id	UUID	发生购买的付费墙的唯一 ID。
vendor_product_id	String	Apple App Store、Google Play 商店或 Stripe 中的产品 ID。

额外的税费和收入事件属性

以下与税费和收入相关的事件属性是仅适用于特定事件类型的附加字段。这意味着所列事件类型包含大多数事件类型的事件属性，以及下方列出的额外字段。

包含税费和收入事件属性的事件类型：

subscription_renewed
subscription_initial_purchase
subscription_refunded
non_subscription_purchase

字段	类型	描述
net_revenue_local	Float	净收入（扣除 Apple/Google 分成及税费后的收入），以本地货币计。
net_revenue_usd	Float	净收入（扣除 Apple/Google 分成及税费后的收入），以美元计。
proceeds_local	Float	扣除 Apple/Google 分成后的产品价格，以本地货币计。
proceeds_usd	Float	扣除 Apple/Google 分成后的产品价格，以美元计。
tax_amount_local	Float	扣除的税费金额，以本地货币计。
tax_amount_usd	Float	扣除的税费金额，以美元计。

访问等级更新事件

Access Level Updated 事件是一种特定的 Webhook 事件，仅在 Webhook 集成处于活跃状态且该事件类型已启用时才会生成。启用后，该事件将被发送至已配置的 Webhook，并显示在 Event Feed 中。若未启用，则不会创建该事件。

如果您已启用共享访问等级，access level updated 事件将发送给所有共享该访问等级的用户画像。

使用此事件可在您的数据库中更新用户的访问等级、在后端授予或撤销高级功能，并保持跨设备或平台的访问同步。

属性	类型	描述
ab_test_name	String	交易来源的 A/B 测试名称。
access_level_id	String	访问等级的 ID。
activated_at	ISO 8601 date	最近一次激活访问的日期和时间。
active_introductory_offer_type	String	应用的新用户优惠类型。可能的值为 `free_trial`、`pay_as_you_go` 和 `pay_up_front`。
active_promotional_offer_id	String	在 Adapty 看板产品部分中标注的促销活动 ID。
active_promotional_offer_type	String	应用的促销活动类型。可能的值为 `free_trial`、`pay_as_you_go` 和 `pay_up_front`。
base_plan_id	String	Google Play 商店中的基础方案 ID 或 Stripe 中的价格 ID。
billing_issue_detected_at	ISO 8601 date	发生计费问题的日期和时间。
cancellation_reason	String	取消的可能原因：`voluntarily_cancelled`、`billing_error`、`price_increase`、`product_was_not_available`、`refund`、`cancelled_by_developer`、`new_subscription_replace`、`upgraded`、`unknown`、`adapty_revoked`。
cohort_name	String	该用户画像所属的目标受众名称。
currency	String	本地货币（默认为 USD）。
developer_id	String	交易来源的版位 ID。
environment	String	可能的值为 `Sandbox` 或 `Production`。
event_datetime	ISO 8601 date	事件的日期和时间。
expires_at	ISO 8601 date	访问权限到期的日期和时间。
is_active	Boolean	表示访问等级是否处于激活状态的布尔值。
is_in_grace_period	Boolean	表示用户画像是否处于宽限期的布尔值。
is_lifetime	Boolean	表示访问等级是否为永久授权的布尔值。
is_refund	Boolean	表示该交易是否为退款的布尔值。
original_purchase_date	ISO 8601 date	对于循环订阅，原始购买是链条中的第一笔交易，其 ID 称为原始交易 ID，用于关联续订链；后续交易均为其延伸。原始购买日期即该第一笔交易的日期和时间。
original_transaction_id	String	对于循环订阅，这是关联续订链的原始交易 ID。原始交易是链条中的第一笔；后续交易均为其延伸。如果没有延伸交易，`original_transaction_id` 与 store_transaction_id 相同。原始购买的交易标识符。
paywall_name	String	交易来源的付费墙名称。
paywall_revision	String	交易来源的付费墙版本。默认值为 1。
profile_country	String	由 Adapty 根据用户画像 IP 确定。
profile_event_id	UUID	可用于去重的唯一事件 ID。
profile_has_access_level	Boolean	表示用户画像是否具有活跃访问等级的布尔值。
profile_id	UUID	Adapty 内部用户画像 ID。
profile_ip_address	String	用户的用户画像 IP 地址。
profile_total_revenue_usd	Float	该用户画像的总收入（含退款）。
purchase_date	ISO 8601 date	产品购买的日期和时间。
renewed_at	ISO 8601 date	访问权限续订的日期和时间。
starts_at	ISO 8601 date	访问等级开始的日期和时间。
store	String	购买产品的商店。标准值：app_store、play_store、stripe、paddle。如果您使用服务端 API 设置了自定义商店交易，则使用 store 参数中的值。
store_country	String	应用商店发送给 Adapty 的国家/地区。
subscription_expires_at	ISO 8601 date	订阅的到期日期。
transaction_id	String	交易的唯一标识符。
trial_duration	String	试用期时长（以天为单位，例如”7 days”）。
variation_id	UUID	实验变体的标识符，用于将购买归因到对应付费墙。
vendor_product_id	String	商店（Apple/Google/Stripe）中的产品 ID。
will_renew	Boolean	表示付费访问等级是否将续订。

请注意，此结构可能会随时间增长——我们或我们合作的第三方可能会引入新数据。请确保处理该结构的代码足够健壮，并依赖特定字段而非整个结构。