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	广告标识符（仅限 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 为每个用户画像自动生成的 Profile ID。如未识别用户或允许在登录前购买，同一个 Apple/Google ID 可能对应不同的 profile 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）Customer User 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 的事件不会包含 base_plan_id 等 Android 专属属性。访问等级已更新事件具有独特的属性，因此我们为其单独设立了一个章节。同样，额外税收与收入事件属性也单独列出，因为它们仅适用于特定事件类型。

适用于大多数事件类型

大多数事件类型的事件属性是一致的（Access Level Updated 事件除外，该事件在其专属章节中单独说明）。下表列出了所有属性，并标注了各属性所属的具体事件。

字段	类型	描述
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 分成前的 USD 产品价格。
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，在看板中创建优惠时由您设置。
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 事件

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	促销活动的 ID，如 Adapty 看板产品部分所示。
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	表示付费访问等级是否将续订。

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