Webhook 让百居易 OpenAPI 用户在指定事件发生时实时收到推送。本文介绍如何配置和使用 OpenAPI Webhook,支持的事件类型包括:
reservation_createdreservation_updatedproperty_availability_updatedlisting_calendar_updatedmessage_createdreview_createdreview_updatedreservation_cancelledguest_review_createdtransaction_createdtransaction_updatedtransaction_deleted
什么是 Webhook
Webhook 是一种应用在事件触发时主动通知另一个应用的机制。事件触发时,百居易会向你指定的 URL 发起 HTTP POST 请求,body 中携带事件详情。
配置 Webhook
在 OpenAPI 开发者后台配置:
- 登录 OpenAPI 设置页。
- 切到 Webhook 设置 Tab。
- 点击 "+ 新增" 按钮。
- 填入接收 Webhook 通知的回调 URL。
Webhook 配额
手动创建、通过自助 access token 创建及历史 webhook 共用账号自有配额。网页端手动创建上限为 3 条,通过 v3 使用自助 access token 创建上限为 5 条。
每个 OAuth 应用在每个账号下独立计配额,默认最多 50 条。应用创建的 webhook 不占用账号自有配额,也不占用其他应用的配额;需要按账号调整时请联系百居易。调低上限不会影响已有 webhook 的正常投递,但配额已满时无法继续新建。
API 创建的 webhook 与解除授权
POST /webhooks 仅创建响应返回 data.id 和 data.secret_token。请安全保存密钥,并用它校验收到的 Hostex-Webhook-Secret-Token 请求头。查询及更新接口不返回密钥;遗失时需删除并重新创建 webhook。密钥属于每条 webhook 记录,重建后会改变。
授权后调用 GET /accounts/me,保存稳定字符串 account_id。主账号及子账号授权共用该 ID。普通业务事件可通过为每个回调地址保存账号 ID 映射来识别账号归属。
房东在后台解除应用授权,或应用通过 OAuth 接口撤销连接时,删除该账号下由该应用通过 API 创建的 webhook。手工创建、缺少应用归属标记的历史记录及其他应用的 webhook 保留。public OAuth client 及支持多个连接的平台应用可保留多套令牌;撤销其中一套时,只要仍有其他令牌就保留应用连接和 webhook,最后一套令牌撤销后才断开整个应用。房东主动解除整个应用授权则撤销全部令牌。
此生命周期事件自动发送,不能作为 events 过滤器中的可选值。向每条被删除的 webhook 原地址发送最后一条 authorization_revoked,使用原密钥,即使其业务事件过滤器未包含该事件。负载包括 account_id、client_id、ULID 字符串 event_id 及 UTC timestamp。应用没有自己创建的 webhook 时,无地址可发送通知。删除后,队列中尚未发送的业务事件会跳过。已发出的请求无法收回,可能在最终通知后抵达;接收方应标记连接为已撤销,重新授权之前忽略后续业务事件。
通知沿用下述超时、立即传输重试及熔断机制,尽力投递,不保证必达,也不延迟重放。重试使用同一个 event_id,请幂等处理。即使通知失败,授权撤销及 webhook 删除仍生效。重新连接后需创建新的 webhook 并保存新密钥。
事件类型
可订阅的事件以及含义:
| 事件 | 描述 |
|---|---|
reservation_created | 新订单创建时触发。 |
reservation_updated | 已有订单更新时触发。 |
property_availability_updated | 房间房态变化时触发。 |
listing_calendar_updated | 渠道侧房源日历更新时触发。 |
message_created | 新消息创建时触发。 |
review_created | 评价创建时触发。 |
review_updated | 评价更新时触发。 |
reservation_cancelled | 订单变为已取消时触发一次。 |
guest_review_created | 房客评价第一次出现时触发一次。 |
transaction_created | 收支流水创建时触发。 |
transaction_updated | 收支流水修改时触发。 |
transaction_deleted | 收支流水删除时触发。 |
我们会持续完善 API,Webhook 推送体可能新增字段。集成方需要解析时 忽略未知字段,而不是拒绝整个通知。
接收和处理 Webhook
你的回调 URL 指向的服务需要解析 POST body,再触发相应的业务逻辑。
安全性
每次 Webhook 请求都会带上请求头 Hostex-Webhook-Secret-Token。该 Token 对每条 webhook 记录唯一,在删除该记录之前保持不变,集成方需要记录这个 Token 并在每次回调时校验一致性,以确认请求来自百居易。
安全注意事项:不要把
Hostex-Webhook-Secret-Token泄露给第三方。仅用于校验来源。
超时处理
每条通知以 HTTP POST 发到你的 URL。百居易连接你的接收端最多等 3 秒,整个请求最多等 5 秒 拿到应答。
- 传输失败会立即重试。 请求没能完成时——连接被拒或超时、DNS 或 TLS 出错、5 秒内没收到应答——百居易会马上重试,两次尝试之间没有间隔。每条通知最多尝试 3 次。
- 每次尝试(包括首次请求)都可能来自不同的 IP 地址。 不要只放行某一个白名单 IP;请按上文用
Hostex-Webhook-Secret-Token校验请求来源。 - 收到 HTTP 应答即视为已送达,返回错误状态码不会触发重试。 例外是
404和410:它们同样不重试,但会被当作「接收端已不存在」计为一次投递失败(见下方「持续失败的接收端会被暂停」)。其他状态码(包括401、403、429、5xx)都算已送达。默认情况下,应用创建的 webhook 在业务事件投递收到410 Gone时还会被删除,恢复投递需重新创建;手动及历史 webhook 保留,404不会触发删除。 - 请配置最终的 HTTPS 地址。 百居易会跟随重定向,但
301、302、303重定向会让请求变成不带 body 的GET,且重定向目标返回的任何应答同样算作已送达。 - 没有延迟补发。 所有尝试都失败后,这条通知即被丢弃,不会稍后再发,也无法重放。
- 持续失败的接收端会被暂停。 同一个 URL 连续投递失败(所有尝试都没拿到应答,或应答为
404/410)时,百居易会暂停向它推送一段时间;暂停期间产生的通知直接丢弃,恢复后也不会补发。URL 还在用的话,请不要用404/410表示「这条通知我不处理」,返回2xx即可。 - 同一条通知可能到达不止一次。 例如接收端处理了请求、但在 5 秒上限之后才应答,重试会再送一次。
建议:
- 收到请求后尽快返回
2xx,耗时处理转入你自己的队列异步完成。 - 通过
event_id幂等处理。每条 v3 通知都包含 26 位 ULID 字符串,同一事件发送到不同 webhook URL 和重试时共用 ID,不同事件使用不同 ID。记录已处理的 ID 并跳过重复通知。它不保证送达或顺序,也不是受影响资源或原始 API 请求的 ID。 - 不要只依赖 Webhook。请定期通过 API 读取当前状态做对账——例如
GET /reservations、GET /conversations、GET /reviews、GET /availabilities或POST /listings/calendar——补上没送达的变化。
示例: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 并正确处理事件,应用就能及时响应百居易的业务变化。注意:
- 尽快返回
2xx应答,远早于 5 秒上限; - 投递失败的通知不会补发,请定期通过 API 对账;
- 对未知事件类型做容错忽略;
- 校验
Hostex-Webhook-Secret-Token确认请求来源。
