Webhook 事件类型

本文列出百居易推送的每种事件的 payload 结构。请先阅读 Webhook 使用指南 了解请求头、投递语义和安全性。

每个 payload 都是一个扁平的 JSON 对象：event、下文列出的事件字段、以及事件入列时的 timestamp（ISO 8601 UTC，如 2026-05-22T02:51:12Z）：

{
  "event": "<event_name>",
  "...各事件字段...": "...",
  "timestamp": "2026-05-22T02:51:12Z"
}

Webhook payload 刻意保持精简：只告诉你什么发生了变化，不携带更多细节。请通过对应的 GET 接口拉取最新状态——把 Webhook 当成「某物变化了，去看看」的信号，而不是完整的变更流。

reservation_created

新订单进入百居易时触发——可能来自任何渠道（Airbnb、Booking.com、通过 POST /reservations 创建的自定义渠道订单等）。

{
  "event": "reservation_created",
  "reservation_code": "ABC123",
  "stay_code": "ABC123",
  "property_id": 12345,
  "timestamp": "2026-05-22T02:51:12Z"
}

多房间订单会按 stay 逐间触发：同一个 reservation_code，每个房间一个不同的 stay_code。

用途：记录新订单、触发入住提醒邮件、生成保洁任务等——请先通过 GET /reservations?reservation_code=<...> 拉取订单详情。

reservation_updated

已有订单发生以下变化时触发：

• 状态变更（如 accepted → cancelled）
• 日期 / 人数变化、换房（allocate）
• 设置入住 / 退房时间（sub_event: arrival_and_departure_time_updated）
• 每晚房价变化（sub_event: rates_updated）
• 门锁密码设置 / 删除（sub_event: lock_code_updated / lock_code_deleted）
• 入住信息更新（sub_event: check_in_details_updated）
• 房东侧 note（订单备注）编辑（sub_event: remarks_updated）
• 通过 OpenAPI 自定义字段接口保存自定义字段（无 sub_event）

可选字段 sub_event 出现时表示具体是上述哪种变化；不出现时按通用变更处理。

{
  "event": "reservation_updated",
  "sub_event": "rates_updated",
  "reservation_code": "ABC123",
  "stay_code": "ABC123",
  "property_id": 12345,
  "timestamp": "2026-05-22T02:51:12Z"
}

Payload 只告诉你 订单发生了变化——如果需要变化后的完整快照，请调用 GET /reservations?id=<...> 拉一次新状态。不要尝试 diff 多次回调的 payload，同一个订单短时间内可能触发多次 reservation_updated。

property_availability_updated

房间在百居易内的每日房态发生变化时触发——不论起因：你的 POST /availabilities 调用、后台操作、订单接单 / 退订导致日期自动关闭或重新开放、iCal 日历导入、房源停用等。

{
  "event": "property_availability_updated",
  "property_id": 12345,
  "availabilities": [
    { "date": "2026-06-01", "available": false },
    { "date": "2026-06-02", "available": false }
  ],
  "timestamp": "2026-05-22T02:51:12Z"
}

Payload 逐日列出受影响的日期——不是日期区间摘要。

listing_calendar_updated

百居易向渠道侧房源成功推送日历变更（价格、库存）后触发——变更来源可能是你的 POST /listings/* 调用，也可能是百居易自身的同步。在渠道（OTA）后台直接修改不会触发此事件。

{
  "event": "listing_calendar_updated",
  "channel_type": "airbnb",
  "listing_id": "12345678",
  "start_date": "2026-06-01",
  "end_date": "2026-06-30",
  "timestamp": "2026-05-22T02:51:12Z"
}

listing_id 是渠道侧的房源标识（始终为字符串）。

用途：让你的价格策略 / 渠道分发系统保持同步，避免轮询房源日历接口。

message_created

会话中产生新消息时触发——可能是房客侧入站、你通过 POST /conversations/{id} 出站、房东在百居易后台或渠道官方 App 发送、或自动化代发。对 OTA 渠道，事件可能延迟数秒到达（渠道同步往返）。

{
  "event": "message_created",
  "conversation_id": "0-2588930000",
  "message_id": "0-31777061577-667553000",
  "timestamp": "2026-05-22T02:51:12Z"
}

两个 id 都是不透明字符串，格式随渠道不同——请原样存储与比较。

⚠️

Payload 不包含发送方信息。请调用 GET /conversations/{id} 并检查该消息的 sender_role 后再行动——把每条 message_created 都当作房客消息的自动回复程序，会回复自己发出的消息并陷入循环。

review_created

百居易首次在渠道上见到某订单的评价记录时触发。部分渠道会在退房前后先创建空的评价记录，因此收到 review_created 并不代表评价内容已存在。

{
  "event": "review_created",
  "reservation_code": "ABC123",
  "stay_code": "ABC123",
  "property_id": 12345,
  "timestamp": "2026-05-22T02:51:12Z"
}

review_updated

该评价记录发生任何后续变化时触发——房客提交评价、房东回复、分数或内容变化。

{
  "event": "review_updated",
  "reservation_code": "ABC123",
  "stay_code": "ABC123",
  "property_id": 12345,
  "timestamp": "2026-05-22T02:51:12Z"
}

建议：对 review_created 和 review_updated 做同样的处理——通过 GET /reviews 拉取最新状态，按实际内容行动。

transaction_created

收支流水创建时触发——可能来自 POST /v3/transactions、百居易后台手工记账，或系统自动记账（如房费退款）。

{
  "event": "transaction_created",
  "transaction_id": 123456,
  "timestamp": "2026-05-22T02:51:12Z"
}

transaction_updated

已有流水被编辑时触发——金额、收支类目、支付方式、action_at（记账日期）或备注变化。注意：编辑不会改变流水的 action_at，只靠 GET /v3/transactions 的日期窗口轮询会漏掉对历史流水的修改，本事件才是可靠的变更信号。

{
  "event": "transaction_updated",
  "transaction_id": 123456,
  "timestamp": "2026-05-22T02:51:12Z"
}

transaction_deleted

流水被删除时触发。删除是永久的——该流水不会再出现在 GET /v3/transactions 的响应里。

{
  "event": "transaction_deleted",
  "transaction_id": 123456,
  "timestamp": "2026-05-22T02:51:12Z"
}

建议：收到 transaction_created / transaction_updated 后通过 GET /v3/transactions?id=<transaction_id> 拉取最新状态；收到 transaction_deleted 后从本地镜像中删除该流水。三个事件配合即可维护一份实时流水镜像，无需每次扫描大日期窗口。

向前兼容

百居易可能在不升级 v3 主版本的前提下，新增事件类型或在已有事件中新增字段。你的处理逻辑必须：

1. 忽略未知事件类型（丢弃或记日志，不要崩溃）；
2. 忽略已知事件里的未知字段；
3. 当 payload 信息不足时回 API 拉取——把 Webhook 当成 "某物变化了，去看看" 的提醒信号，而不是完整的变更流。