开发

Webhook 入门指南

更新时间: 2025年3月26日
Webhook 可通过 HTTP 请求实现实时通知，从而提供特定字段事件的即时更新。例如，当您应用的用户加入新的大厅或会话，甚至开始订阅时，您都会收到通知。这样，您就不需要查询变更，有助于避免达到流量上限⁠。

设置接收 Webhook 通知的服务器

为了接收 Webhook 通知，您的服务器必须能够接受和处理 HTTPS，并且必须安装有效的 TLS 或 SSL 证书。不支持自签名证书。
如需详细了解如何设置用来接收 Webhook 通知请求的服务器，请参阅 Facebook 开发者文档中的创建端点⁠。

在 Meta Horizon 开发者面板中为应用设置 Webhook

如要设置 Webhook：
  1. 在 Meta Horizon 开发者面板⁠中，点击开发 > Webhook，然后在下拉菜单中选择您的应用。
    Accessing Webhooks Configuration in the App Dashboard
  2. 在 Webhook 页面中，点击设置 Webhook。
    Setup a Webhooks Subscription
  3. 在回调网址字段中，输入端点的网址。在验证口令字段中，提供可以用来验证 Facebook 认证请求⁠的值。
    Configure a Webhooks Subscription
  4. 如要将已更改的字段名称及其新值包含在事件通知有效负载中，请开启包含值。
  5. 点击创建然后，Facebook 会向您的端点发送认证请求，您必须对其进行验证⁠。如果您的端点设置正确，则 Webhook 对话框应类似于下图。
    Successful Creation of a Webhooks Subscription
  6. 要完成此操作，请点击您想要发送相关通知的 Webhook 字段旁的订阅。
如果希望向您的端点发送测试通知，请确保已在设置中启用 Webhook，然后执行以下操作：
  1. 为您想要为其发送测试通知的字段点击测试。
    Testing Subscription
  2. 在字段示例显示框中，点击发送到我的服务器。
    Testing Subscription

Webhook 字段参考

可在单个通知请求中批处理多个 Webhook 字段事件，但并不保证每个请求都能如此。请在下方所示的更改字段中处理在单个 Webhook 通知请求中只发送一个字段事件或发送多个字段事件的场景。

Webhook 通知请求基本结构

{
  "entry": [
    {
      "id": string,
      "time": number (Unix Timestamp),
      "changes": Array<WebhookFieldEvent>
    }
  ],
  "object": "application"
}

多人游戏字段

join_intent

当用户接受游戏内邀请或重新加入多人游戏会话时，系统向您的服务器发送 join_intent 事件。
此事件可用于以下用途：
  • 通知用户有新玩家即将加入目标位置；
  • 使用 lobby_session_id 和 match_session_id 为即将加入的玩家预留大厅位置；
  • 处理在预期用户加入前可完成的服务器端额外逻辑。
{
  "entry": [
    {
      "id": "345533925309564",
      "time": 1718052945,
      "changes": [
        {
          "field": "join_intent",
          "value": {
            "destination_api_name": "destination_api_name",
            "joining_user": "10149999707612630",
            "lobby_session_id": "test_lobby_session_id",
            "match_session_id": "test_match_session_id"
          }
        }
      ]
    }
  ],
  "object": "application"
}

值

名称类型描述
destination_api_name
string
用户打算加入的目标位置的 API 名称。
joining_user
string
即将加入的用户的编号。
lobby_session_id
string
用户打算加入的大厅会话的编号。
match_session_id
string
用户打算加入的比赛会话的编号。

订单字段

order_status

如果用户完成任何附加内容的购买流程，或任何现有附加内容购买流程有所更新（例如消费、退款、拒付），系统会向您的服务器发送 order_status 事件。
此事件可用于以下用途：
  • 追踪应用程序附加内容的新购买情况
  • 追踪应用程序附加内容的退款情况
{
  "entry": [
    {
      "id": "345533925309564",
      "time": 1718052945,
      "changes": [
        {
          "field": "order_status",
          "value": {
            "event_time": "1659742639",
            "user_id": "10149999707612630",
            "product_info": {
              "notification_type": "PURCHASED",
              "reporting_id": "03f8833e-9c02-4fa0-978f-4cfe91f86bae",
              "sku": "item_sku_1",
              "developer_payload": "{\"quoteId\": 1234567}"
            }
          }
        }
      ]
    }
  ],
  "object": "application"
}

值

名称类型描述
event_time
Unix timestamp
下单时间。
user_id
numeric string
附加内容的所有者。
product_info
dict
包含订单/商品详情的对象。
product_info.notification_type
string
订单事件类型。（PURCHASED、REFUNDED、CHARGEBACKED）
product_info.reporting_id
string
出于报告目的为订单生成的独立 UUID。
product_info.sku
string
该订单的应用内购买商品的独立 SKU。
product_info.developer_payload
dict
包含开发者精选信息的未格式化字符串。

订阅字段

如要订阅“订阅 Webhook 字段”，您必须完成针对订阅和用户编号的数据使用情况检查。

subscription_started

当用户开始订阅您的应用程序时，系统会向您的服务器发送 subscription_started 事件。这可能是新的订阅，也可能是订阅过期后重新开始订阅。
{
  "entry": [
    {
      "id": "345533925309564",
      "time": 1715797294,
      "changes": [
        {
          "field": "subscription_started",
          "value": {
            "owner_id": "1234567890",
            "source_app": "TWILIGHT",
            "subscription": {
              "id": "1234567890",
              "trial_type": "TRIAL_OFFER",
              "sku": "bronzeTier0",
              "period_start_time": "1711956272",
              "period_end_time": "1711956272",
              "next_renewal_time": "1711956272",
              "is_active": true,
              "is_trial": false,
              "current_price_term": {
                "term": "MONTHLY",
                "price": "19.99",
                "currency": "USD"
              },
              "next_price_term": {
                "term": "MONTHLY",
                "price": "1999.00",
                "currency": "USD"
              }
            }
          }
        }
      ]
    }
  ],
  "object": "application"
}

subscription_renewal_success

当现有的应用程序订阅成功续订后，系统会向您的服务器发送 subscription_renewal_success 事件。订阅会定期续订，而且续订数量与有效订阅量相关，因此，如果您决定订阅此 Webhook 字段，请务必确保您的服务器能够处理大量可能同时进行的 subscription_renewal_success Webhook 事件请求。为了有效管理此类流量，如果您的应用程序存在大量订阅，则请验证您的服务器是否有能力处理如此大的工作量。
{
  "entry": [
    {
      "id": "345533925309564",
      "time": 1715796778,
      "changes": [
        {
          "field": "subscription_renewal_success",
          "value": {
            "owner_id": "1234567890",
            "subscription": {
              "id": "1234567890",
              "sku": "bronzeTier0",
              "period_start_time": "1711956272",
              "period_end_time": "1711956272",
              "next_renewal_time": "1711956272",
              "is_active": true,
              "is_trial": false,
              "current_offer": {
                "term": "MONTHLY",
                "price": "19.99",
                "currency": "USD"
              },
              "next_offer": {
                "term": "MONTHLY",
                "price": "19.99",
                "currency": "USD"
              }
            }
          }
        }
      ]
    }
  ],
  "object": "application"
}

subscription_canceled

当用户取消订阅您的应用程序时，系统会向您的服务器发送 subscription_canceled 事件。
{
  "entry": [
    {
      "id": "345533925309564",
      "time": 1717714215,
      "changes": [
        {
          "value": {
            "owner_id": "7663588487057119",
            "subscription": {
              "id": "228e599134540916c63a33cd6aa485379deb3a959ba4075f323b31bb1dda7ecc",
              "sku": "bronze_test_01",
              "period_start_time": "1717714180",
              "period_end_time": "1720306180",
              "next_renewal_time": "1720306180",
              "is_active": true,
              "is_trial": false,
              "current_price_term": {
                "term": "MONTHLY",
                "price": "1.99",
                "currency": "USD"
              },
              "next_price_term": {
                "term": "MONTHLY",
                "price": "1.99",
                "currency": "USD"
              }
            },
            "cancel_reason": "PRICE_TOO_EXPENSIVE"
          },
          "field": "subscription_canceled"
        }
      ]
    }
  ],
  "object": "application"
}

subscription_uncanceled

如果用户在应用程序订阅过期前不取消订阅，系统会向您的服务器发送 subscription_uncanceled 事件。
{
  "entry": [
    {
      "id": "345533925309564",
      "time": 1717714175,
      "changes": [
        {
          "value": {
            "owner_id": "7663588487057119",
            "subscription": {
              "id": "228e599134540916c63a33cd6aa485379deb3a959ba4075f323b31bb1dda7ecc",
              "sku": "bronze_test_01",
              "period_start_time": "1717713920",
              "period_end_time": "1720305920",
              "next_renewal_time": "1720305920",
              "is_active": true,
              "is_trial": false,
              "current_price_term": {
                "term": "MONTHLY",
                "price": "1.99",
                "currency": "USD"
              },
              "next_price_term": {
                "term": "MONTHLY",
                "price": "1.99",
                "currency": "USD"
              }
            }
          },
          "field": "subscription_uncanceled"
        }
      ]
    }
  ],
  "object": "application"
}

subscription_expired

当应用程序订阅过期时，系统会向您的服务器发送 subscription_expired 事件。订阅会定期过期，而且过期数量与已取消的订阅量相关，因此，如果您决定订阅此 Webhook，请务必确保您的服务能够处理大量可能同时进行的 subscription_expired Webhook 事件请求。为了有效管理此类流量，如果您的应用程序存在大量订阅，则请验证您的服务器是否有能力处理如此大的工作量。
{
  "entry": [
    {
      "id": "345533925309564",
      "time": 1717714227,
      "changes": [
        {
          "value": {
            "owner_id": "7663588487057119",
            "subscription": {
              "id": "228e599134540916c63a33cd6aa485379deb3a959ba4075f323b31bb1dda7ecc",
              "sku": "bronze_test_01",
              "period_start_time": "1717714180",
              "period_end_time": "1717714221",
              "next_renewal_time": "1717714221",
              "is_active": false,
              "is_trial": false,
              "current_price_term": {
                "term": "MONTHLY",
                "price": "1.99",
                "currency": "USD"
              },
              "next_price_term": {
                "term": "MONTHLY",
                "price": "1.99",
                "currency": "USD"
              }
            }
          },
          "field": "subscription_expired"
        }
      ]
    }
  ],
  "object": "application"
}

值

名称类型描述
owner_id
string
订阅所属用户的应用范围用户编号
source_app
string
针对 subscription_started 事件开始订阅的 Meta 应用程序。
subscription
Subscription
与事件相关的订阅数据。
cancel_reason
string
针对 subscription_canceled 事件取消订阅的原因。

订阅

名称类型描述
id
string
订阅的唯一标识符，在所有订阅字段事件中保持一致。可用于将所有订阅事件关联到此标识符。
trial_type
?string
如果订阅目前处于新人优惠价或试用阶段，则设为 INTRO_OFFER 或 TRIAL_OFFER。如果是正常付费订阅，则无需设置。
sku
string
订阅计划的 SKU 标识符。
period_end_time
string
当期订阅期结束时的 Unix 时间戳。
period_start_time
string
当期订阅开始时的 Unix 时间戳。
next_renewal_time
string
订阅续订时的 Unix 时间戳。
current_price_term
price_term
当期订阅的价格和期限。
next_price_term
price_term
下次续订时适用的价格和期限。
is_active
bool
当订阅处于有效状态时，设为 True。
is_trial
bool
当最近的订阅期是免费试用（7d、14d、30d）时，设为 Ture。不表示订阅本身处于有效状态。

价格期限

名称类型描述
term
string?
订阅期限（例如：MONTHLY、ANNUAL、WEEKLY 等）。对于试用订阅，此字段可能为空。
currency
string
价格所用的货币单位。例如：USD、EUR
price
string
不带货币符号的订阅价格。
导航徽标
虚拟现实 / Meta Horizon
虚拟现实 / Meta Horizon
虚拟现实 / Meta Horizon
中文(简体)
© 2026 Meta