Webhook 让百居易 OpenAPI 用户在指定事件发生时实时收到推送。本文介绍如何配置和使用 OpenAPI Webhook，支持的事件类型包括：
reservation_createdreservation_updatedproperty_availability_updatedlisting_calendar_updatedmessage_createdreview_createdreview_updated
什么是 Webhook
Webhook 是一种应用在事件触发时主动通知另一个应用的机制。事件触发时，百居易会向你指定的 URL 发起 HTTP POST 请求，body 中携带事件详情。
配置 Webhook
在 OpenAPI 开发者后台配置：
- 登录 OpenAPI 设置页。
- 切到 Webhook 设置 Tab。
- 点击 "+ 新增" 按钮。
- 填入接收 Webhook 通知的回调 URL。
事件类型
可订阅的事件以及含义：
| 事件 | 描述 |
|---|---|
reservation_created | 新订单创建时触发。 |
reservation_updated | 已有订单更新时触发。 |
property_availability_updated | 房间房态变化时触发。 |
listing_calendar_updated | 渠道侧房源日历更新时触发。 |
message_created | 新消息创建时触发。 |
review_created | 评价创建时触发。 |
review_updated | 评价更新时触发。 |
我们会持续完善 API，Webhook 推送体可能新增字段。集成方需要解析时 忽略未知字段，而不是拒绝整个通知。
接收和处理 Webhook
你的回调 URL 指向的服务需要解析 POST body，再触发相应的业务逻辑。
安全性
每次 Webhook 请求都会带上请求头 Hostex-Webhook-Secret-Token。该 Token 在每个 URL 上唯一且固定，集成方需要记录这个 Token 并在每次回调时校验一致性，以确认请求来自百居易。
安全注意事项：不要把
Hostex-Webhook-Secret-Token泄露给第三方。仅用于校验来源。
超时处理
Webhook 接收端必须在 3 秒 内返回 2xx 应答确认收到，否则该通知 不会重试。请保证回调处理快速完成；耗时任务可以转入队列异步处理。
示例：Node.js Express Webhook 接收端
const express = require('express');
const bodyParser = require('body-parser');
const app = express();
app.use(bodyParser.json());
app.post('/webhook-endpoint', (req, res) => {
const eventType = req.body.event;
switch(eventType) {
case 'reservation_created':
// 处理新订单
break;
case 'reservation_updated':
// 处理订单更新
break;
case 'property_availability_updated':
// 处理房间房态变化
break;
case 'listing_calendar_updated':
// 处理渠道日历更新
break;
case 'message_created':
// 处理新消息
break;
case 'review_created':
// 处理评价创建
break;
case 'review_updated':
// 处理评价更新
break;
default:
// 未知事件类型，忽略
}
// 立刻应答，避免超时
res.status(200).send('Event received');
});
const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
console.log(`Server is listening on port ${PORT}`);
});
总结
配置好 Webhook 并正确处理事件，应用就能及时响应百居易的业务变化。注意：
- 在 3 秒内应答确认收到；
- 对未知事件类型做容错忽略；
- 校验
Hostex-Webhook-Secret-Token确认请求来源。