事件类型

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

新订单进入百居易时触发——可能来自任何渠道(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

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

  • 状态变更(如 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

房间在百居易内的每日房态发生变化时触发——不论起因:你的 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

百居易向渠道侧房源成功推送日历变更(价格、库存)后触发——变更来源可能是你的 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

会话中产生新消息时触发——可能是房客侧入站、你通过 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 并不代表评价内容已存在。

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

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

订单状态变为 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

房客对某次入住的评价第一次出现在百居易时触发一次,也就是 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

每新建一条收支流水发送一次,不论来源:百居易网页端或 App(收支页记一笔、在订单上添加收支、续住收款、费用收款或退款、手工订单收款、任务费用)、POST /v3/transactions,或百居易自动生成(如押金结算)。

百居易随订单自动同步维护的流水不在此列:渠道订单的房费,以及 BookingSite 订单的房费、退款和支付手续费。这些流水不发送任何收支事件。

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

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

每删除一条收支流水发送一次,不论来源:百居易网页端或 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 主版本的前提下,新增事件类型或在已有事件中新增字段。你的处理逻辑必须:

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

authorization_revoked

OAuth 应用解除授权后的最终生命周期通知。发送至该账号下由该应用通过 API 创建的 webhook 地址,忽略业务事件过滤器,使用各 webhook 的原密钥。开始投递时 webhook 注册及令牌已删除,不包含个人信息。多设备行为与投递限制见 使用指南。

{
  "event": "authorization_revoked",
  "event_id": "01K71WRG00R6PR4FPYRXBNNRWB",
  "account_id": "12345",
  "client_id": "your_application_id",
  "timestamp": "2026-10-09T02:00:00Z"
}