Webhook 事件类型
本文列出百居易推送的每种事件的 payload 结构。请先阅读 Webhook 使用指南 了解请求头、投递语义和安全性。
每个 payload 都是一个扁平的 JSON 对象:event、字符串 event_id、下文列出的事件字段、以及事件入列时的 timestamp(ISO 8601 UTC,如 2026-05-22T02:51:12Z):
所有 v3 事件(包括 authorization_revoked)都包含 26 位 ULID 字符串 event_id。同一事件发送到不同 webhook URL 或重试时使用同一个 ID,不同事件使用不同 ID。请用 event_id 去重;它标识通知,不是业务资源 ID,也不关联触发它的 API 请求,不保证送达或顺序。
{
"event": "<event_name>",
"event_id": "01K71WRG00R6PR4FPYRXBNNRW0",
"...各事件字段...": "...",
"timestamp": "2026-05-22T02:51:12Z"
}
Webhook payload 刻意保持精简:只告诉你什么发生了变化,不携带更多细节。请通过对应的
GET接口拉取最新状态——把 Webhook 当成「某物变化了,去看看」的信号,而不是完整的变更流。
reservation_created
reservation_created新订单进入百居易时触发——可能来自任何渠道(Airbnb、Booking.com、通过 POST /reservations 创建的自定义渠道订单等)。
{
"event": "reservation_created",
"event_id": "01K71WRG00R6PR4FPYRXBNNRW1",
"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
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",
"event_id": "01K71WRG00R6PR4FPYRXBNNRW2",
"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
property_availability_updated房间在百居易内的每日房态发生变化时触发——不论起因:你的 POST /availabilities 调用、后台操作、订单接单 / 退订导致日期自动关闭或重新开放、iCal 日历导入、房源停用等。
{
"event": "property_availability_updated",
"event_id": "01K71WRG00R6PR4FPYRXBNNRW3",
"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
listing_calendar_updated百居易向渠道侧房源成功推送日历变更(价格、库存)后触发——变更来源可能是你的 POST /listings/prices / POST /listings/inventories 调用,也可能是百居易自身的同步。在渠道(OTA)后台直接修改不会触发此事件。
以下情况不会触发:
POST /listings/restrictions、POST /listings/airbnb/price_and_rules、POST /listings/vrbo/price_and_rules直接写渠道,从不发送此事件。- 推送失败,或推送以警告而非完全成功结束。
{
"event": "listing_calendar_updated",
"event_id": "01K71WRG00R6PR4FPYRXBNNRW4",
"channel_type": "airbnb",
"listing_id": "12345678",
"start_date": "2026-06-01",
"end_date": "2026-06-30",
"timestamp": "2026-05-22T02:51:12Z"
}
listing_id 是渠道侧的房源标识(始终为字符串)。
这个事件能说明什么、不能说明什么:
- 它通常表示渠道接受了这次推送。百居易不会再从渠道回读日历来核实。
- 它不带与触发它的 API 请求关联的标识,请按
channel_type+listing_id+ 日期匹配。timestamp是事件入列时间,不是渠道生效时间。 - 渠道、房源、日期范围都相同的事件,5 秒窗口内只发第一条;窗口内之后产生的相同事件直接丢弃——不会并入你收到的那次投递,之后也不会再单独通知。如需拿到最终值,收到事件后稍等几秒再读,并依赖定期对账。
用途:让你的价格策略 / 渠道分发系统保持同步,减少对房源日历接口的轮询。由于投递失败的通知不会补发(见 Webhook 使用指南),仍建议定期用 POST /listings/calendar 对账。
message_created
message_created会话中产生新消息时触发——可能是房客侧入站、你通过 POST /conversations/{id} 出站、房东在百居易后台或渠道官方 App 发送、或自动化代发。对 OTA 渠道,事件可能延迟数秒到达(渠道同步往返)。
{
"event": "message_created",
"event_id": "01K71WRG00R6PR4FPYRXBNNRW5",
"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百居易首次在渠道上见到某订单的评价记录时触发。部分渠道会在退房前后先创建空的评价记录,因此收到 review_created 并不代表评价内容已存在。
{
"event": "review_created",
"event_id": "01K71WRG00R6PR4FPYRXBNNRW6",
"reservation_code": "ABC123",
"stay_code": "ABC123",
"property_id": 12345,
"timestamp": "2026-05-22T02:51:12Z"
}
review_updated
review_updated该评价记录发生任何后续变化时触发——房客提交评价、房东回复、分数或内容变化。
{
"event": "review_updated",
"event_id": "01K71WRG00R6PR4FPYRXBNNRW7",
"reservation_code": "ABC123",
"stay_code": "ABC123",
"property_id": 12345,
"timestamp": "2026-05-22T02:51:12Z"
}
建议:对 review_created 和 review_updated 做同样的处理——通过 GET /reviews 拉取最新状态,按实际内容行动。
reservation_cancelled
reservation_cancelled订单状态变为 cancelled 时触发一次,无论是在渠道上取消还是在百居易里取消。已取消订单之后的更新不会再次触发;订单恢复后再次取消,会再触发一次。同一次变化仍会照常发送 reservation_updated。
只有变为 cancelled 才算:最终为 denied 或 timeout 的预订申请不会触发。在百居易里拒绝的预订申请可能被记为 cancelled,这种情况会触发。百居易首次导入时就已取消的订单只会发送 reservation_created。
{
"event": "reservation_cancelled",
"event_id": "01K71WRG00R6PR4FPYRXBNNRWC",
"reservation_code": "ABC123",
"stay_code": "ABC123",
"property_id": 12345,
"timestamp": "2026-05-22T02:51:12Z"
}
多房间订单按取消的 stay 逐间触发:同一个 reservation_code,每个房间一个不同的 stay_code。
guest_review_created
guest_review_created房客对某次入住的评价第一次出现在百居易时触发一次,也就是 GET /reviews?reservation_code=<...> 开始返回该订单的 guest_review 的时候。部分渠道会在退房时先创建空的评价记录并触发 review_created;本事件不同,它表示房客已经提交了评价。同一次变化仍会照常发送 review_created 或 review_updated;之后的修改和房东回复只发送 review_updated。
{
"event": "guest_review_created",
"event_id": "01K71WRG00R6PR4FPYRXBNNRWD",
"reservation_code": "ABC123",
"stay_code": "ABC123",
"property_id": 12345,
"timestamp": "2026-05-22T02:51:12Z"
}
transaction_created
transaction_created每新建一条收支流水发送一次,不论来源:百居易网页端或 App(收支页记一笔、在订单上添加收支、续住收款、费用收款或退款、手工订单收款、任务费用)、POST /v3/transactions,或百居易自动生成(如押金结算)。
百居易随订单自动同步维护的流水不在此列:渠道订单的房费,以及 BookingSite 订单的房费、退款和支付手续费。这些流水不发送任何收支事件。
{
"event": "transaction_created",
"event_id": "01K71WRG00R6PR4FPYRXBNNRW8",
"transaction_id": 123456,
"timestamp": "2026-05-22T02:51:12Z"
}
transaction_updated
transaction_updated已有流水被编辑时触发——金额、收支类目、支付方式、action_at(记账日期)或备注变化。注意:编辑不会改变流水的 action_at,只靠 GET /v3/transactions 的日期窗口轮询会漏掉对历史流水的修改,本事件才是可靠的变更信号。
部分新建方式(例如在订单上添加收支)会在 transaction_created 之后紧跟着为同一条流水再发一条 transaction_updated。请按 transaction_id 回查,以流水的当前状态为准。
{
"event": "transaction_updated",
"event_id": "01K71WRG00R6PR4FPYRXBNNRW9",
"transaction_id": 123456,
"timestamp": "2026-05-22T02:51:12Z"
}
transaction_deleted
transaction_deleted每删除一条收支流水发送一次,不论来源:百居易网页端或 App(包括删除或取消费用、任务、手工订单时连带删掉的流水),或 DELETE /v3/transactions/{id}。删除是永久的——该流水不会再出现在 GET /v3/transactions 的响应里。
{
"event": "transaction_deleted",
"event_id": "01K71WRG00R6PR4FPYRXBNNRWA",
"transaction_id": 123456,
"timestamp": "2026-05-22T02:51:12Z"
}
建议:收到 transaction_created / transaction_updated 后通过 GET /v3/transactions?id=<transaction_id> 拉取最新状态;收到 transaction_deleted 后从本地镜像中删除该流水。三个事件配合即可维护一份实时流水镜像,无需每次扫描大日期窗口。
向前兼容
百居易可能在不升级 v3 主版本的前提下,新增事件类型或在已有事件中新增字段。你的处理逻辑必须:
- 忽略未知事件类型(丢弃或记日志,不要崩溃);
- 忽略已知事件里的未知字段;
- 当 payload 信息不足时回 API 拉取——把 Webhook 当成 "某物变化了,去看看" 的提醒信号,而不是完整的变更流。
authorization_revoked
authorization_revokedOAuth 应用解除授权后的最终生命周期通知。发送至该账号下由该应用通过 API 创建的 webhook 地址,忽略业务事件过滤器,使用各 webhook 的原密钥。开始投递时 webhook 注册及令牌已删除,不包含个人信息。多设备行为与投递限制见 使用指南。
{
"event": "authorization_revoked",
"event_id": "01K71WRG00R6PR4FPYRXBNNRWB",
"account_id": "12345",
"client_id": "your_application_id",
"timestamp": "2026-10-09T02:00:00Z"
}
