Webhook 事件类型

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

所有 payload 共用一个信封：

{
  "event": "<event_name>",
  "data":  { /* 各事件不同，见下 */ },
  "timestamp": "2026-05-22T02:51:12Z"
}

Payload 字段名与对应的 GET /<resource> 响应保持一致——字段的具体类型请参考 API Reference 中的接口文档。

`reservation_created`

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

{
  "event": "reservation_created",
  "data": {
    "reservation_code": "ABC123",
    "stay_code": "ABC123",
    "channel_type": "airbnb",
    "property_id": 12345,
    "check_in_date": "2026-06-01",
    "check_out_date": "2026-06-05",
    "status": "accepted",
    "guest": {
      "name": "Jane Doe",
      "email": "[email protected]",
      "phone": "+1 555 123 4567"
    },
    "booked_at": "2026-05-22T02:50:00+00:00"
  }
}

用途：记录新订单、触发入住提醒邮件、提前一天生成保洁任务等。

`reservation_updated`

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

状态变更（如 accepted → cancelled）
日期 / 人数变化
换房 / 拆单
收费金额变化（新增或修改 ReservationCharge）
标签新增 / 移除
房东侧 note（订单备注）编辑

{
  "event": "reservation_updated",
  "data": {
    "reservation_code": "ABC123",
    "stay_code": "ABC123",
    "channel_type": "airbnb",
    "property_id": 12345,
    "status": "cancelled",
    "...": "..."
  }
}

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

`property_availability_updated`

房间在 百居易侧 的房态被 POST /availabilities（或后台操作）修改时触发。渠道侧日历变更走 listing_calendar_updated，不在此事件覆盖范围内。

{
  "event": "property_availability_updated",
  "data": {
    "property_id": 12345,
    "start_date": "2026-06-01",
    "end_date": "2026-06-30",
    "available": false,
    "source": "openapi"
  }
}

`listing_calendar_updated`

渠道侧房源日历变化时触发（价格、库存、限制）——来源可能是你通过 POST /listings/* 推送，也可能是百居易自动同步渠道侧改动。

{
  "event": "listing_calendar_updated",
  "data": {
    "channel_account_id": 9876,
    "channel_type": "airbnb",
    "listing_id": "12345-ABC",
    "property_id": 12345,
    "fields_changed": ["price", "min_nights"],
    "start_date": "2026-06-01",
    "end_date": "2026-06-30"
  }
}

用途：让你的价格策略 / 渠道分发系统保持同步，避免轮询 POST /listings/calendar。

`message_created`

任意会话中产生新消息时触发——可能是房客侧入站、你通过 POST /conversations/{id} 出站、或者是百居易后台直接发出。

{
  "event": "message_created",
  "data": {
    "message_id": "msg_abc",
    "conversation_id": "thread_xyz",
    "channel_type": "airbnb",
    "sender_role": "guest",
    "sender_name": "Jane Doe",
    "display_type": "Text",
    "content": "你好，几点可以入住？",
    "created_at": "2026-05-22T02:51:12+00:00"
  }
}

如果需要完整会话上下文（动作、备注等），可调用 GET /conversations/{id}。这是搭建实时收件箱 UI 推荐的触发源。

`review_created`

新评价产生时触发——可能来自房客、房东（通过 POST /reviews/{reservation_code} 或百居易后台）。

{
  "event": "review_created",
  "data": {
    "reservation_code": "ABC123",
    "channel_type": "airbnb",
    "property_id": 12345,
    "review_status": "reviewed",
    "rating": 5,
    "comment": "住得很舒服！",
    "...": "..."
  }
}

`review_updated`

已有评价更新时触发——常见场景是房东新增 / 编辑 / 删除回复。

{
  "event": "review_updated",
  "data": {
    "reservation_code": "ABC123",
    "channel_type": "airbnb",
    "property_id": 12345,
    "rating": 5,
    "host_reply": "感谢入住！",
    "...": "..."
  }
}

向后兼容

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

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