跳到主要内容

设置出站 Webhook 投递

快速设置

大多数酒店可在 5 到 10 分钟内完成设置。

本指南帮助你在住客验证和 PMS 同步后发送 JSON guest_verified 事件。

前往： Settings → Outbound Webhook

签名头

每次投递都会包含 X-Vouch-Signature。 你的接收端应先验证该请求头，再信任载荷。

敏感值

任何可以访问此页面的人都能看到已保存的请求头值和 HMAC 签名密钥。 投递日志会显示完整的请求载荷和响应详情。 审计变更记录仍会对这些值进行脱敏。 请保护 Settings → Outbound Webhook 的访问权限，并避免分享屏幕截图。

快速参考​

设置控制内容你会看到
Enabled打开或关闭出站 Webhook 投递保存后开关保持开启
Webhook URL投递的目标 URLAVA 接受你的接收端 URL
Headers发给接收端的静态认证头保存后已保存的值仍可见
Payload Fields发送哪些住客字段只有勾选的字段会出现在投递中
Marketing consent是否包含顶层 marketingConsent状态卡显示 Included 或 Omitted
Max attempts失败投递的重试次数数值保持在 1 到 10 之间
HMAC signing secret为每次投递签名载荷已保存的值仍可见；启用或测试时必须填写
Send Test发送一次测试投递最新测试会出现在 Delivery Logs 中
Delivery Logs最近的投递状态和载荷每页显示 10 条记录，以及状态、尝试次数、HTTP 状态、响应正文、载荷详情和分页导航

开始前​

先确认这些基础项：

  • 你有 settings:write 权限
  • 你知道接收端 URL
  • 你知道所需的静态认证头
  • 你有 HMAC 签名密钥
  • 你知道接收端需要哪些住客字段
已保存的密钥值

保存后，已保存的请求头值和 HMAC 签名密钥仍会显示。 需要轮换密钥时，请输入新值。

发送时机​

住客验证成功后，AVA 会发送 Webhook。 事件名称为 guest_verified。 如果 PMS 同步失败，AVA 不会发送 Webhook。

请求使用 JSON POST。 AVA 会在每次投递中附带你的静态请求头。

配置 Webhook​

打开 Webhook​

  1. 前往 Settings → Outbound Webhook。

  2. 打开 Enabled。

  3. 输入 Webhook URL。

  4. 点击 Save。

    ✓ AVA 会保存该端点供后续投递使用。

添加自定义请求头​

当接收端需要静态身份验证时，使用请求头。 AVA 会在每次 JSON POST 中发送这些请求头。 例如，你可以发送 Authorization: token api_key:api_secret。

  1. 点击 Add。

  2. 输入请求头名称。

  3. 输入请求头值。

  4. 对敏感值打开 Secret。

  5. 点击 Save。

    ✓ 保存后，已保存的请求头值仍可见。

选择载荷字段​

在 Payload Fields 卡片中选择接收端需要的字段。 该目录包含预订字段，以及 Settings → Check-In → Registration Form 中的所有字段。 营销同意不属于此清单。

  1. 勾选你要发送的每个字段。

  2. 取消勾选接收端不需要的字段。

  3. 点击 Save。

    ✓ 未来的投递中只会包含已勾选的字段。

可用的载荷字段​

分组AVA 中的字段JSON 属性
预订确认号码reservation.confirmationNumber
预订到店日期reservation.arrivalDate
预订离店日期reservation.departureDate
住客名字guest.firstName
住客姓氏guest.lastName
住客电子邮箱guest.email
住客电话guest.phone
住客国籍guest.nationality
住客证件号码guest.documentNumber
住客出生日期guest.birthDate
住客邮政编码guest.postalCode
住客居住国guest.countryCode
住客地址guest.addressLine
住客城市guest.cityName
住客州或省guest.stateProv
住客入住目的guest.purposeOfStay
住客预计到店时间guest.preCheckInTime
住客性别guest.gender
住客职业guest.occupation
住客出发地guest.placeOfDeparture
住客下一目的地guest.nextDestination
住客离店时间guest.departureTime

如果所选字段为空，AVA 可能会从 JSON 中省略该属性。 入住目的和预计到店时间可以使用已保存的入住登记值。 AVA 会合并地址各部分，用于出发地和下一目的地。 如果住客选择当前地址，AVA 会将该地址用于目的地。

Marketing consent 卡片显示四项值：

  • Guest prompt — 住客是否会看到营销选择加入提示
  • Collection setting — PMS 使用的同意模式
  • Registration field — Marketing consent 是否可见
  • Webhook payload — AVA 是否包含 marketingConsent

Payload Fields 清单不会改变这些值。

  1. 前往 Settings → Check-In → Card & Consent。

  2. 如需详细同意设置，启用 Promotional Mailing List。

  3. 如需通用同意设置，启用 Show marketing email opt-in during signature。

  4. 前往 Settings → Check-In → Registration Form。

  5. 对 Marketing consent，将 Show to 设置为 All guests。

  6. 保存这两个设置页面。

    ✓ 两项前置条件都满足后，状态卡会显示 Included。 ✓ AVA 会根据住客的选择发送 true 或 false。

当选择加入功能被禁用或字段被隐藏时，AVA 会省略 marketingConsent。 仅启用电话和电子邮箱联系同意不会启用营销同意。

设置重试次数和签名密钥​

临时投递失败时可使用重试。 设置签名密钥后，接收端就能验证每个载荷。

  1. 在 Max attempts 中输入一个值。

  2. 使用 1 到 10 之间的数值。

  3. 输入你的 HMAC signing secret。

  4. 点击 Save。

    ✓ AVA 会重试 429、5xx 和超时失败。 ✓ 校验错误和身份验证错误会保留在日志中，不会重试。

替换已保存的密钥​

当请求头密钥或签名密钥已经存在时使用此项。 当前已保存的值会直接显示在对应字段中。

  1. 选中请求头或 HMAC 字段中的当前值。

  2. 输入新值。

  3. 点击 Save。

    ✓ 保存后会显示新值，并应用于后续投递。

发送测试投递​

保存设置后可发送测试投递。 测试会使用最近保存的配置。 测试也会使用已保存的 HMAC 签名密钥。

  1. 点击 Send Test。

  2. 等待成功消息。

  3. 打开 Delivery Logs，确认出现新行。

    ✓ 最新一行会显示 test delivery。

先保存

如果你修改了页面上的任何内容，请先保存再发送测试。 在已保存的更改清除之前，AVA 会禁用测试按钮。

查看投递日志​

投递日志可帮助你检查最近的尝试。 每页显示 10 行。 每行显示投递状态、时间戳、尝试次数、HTTP 状态和详情。 你还可以打开完整的请求载荷和响应正文。 使用分页控件在较早和较新的投递之间切换。

状态含义
delivered接收端已接受该投递
processingAVA 仍在处理该投递
retryingAVA 稍后会再次尝试
pendingAVA 已将该投递排队
failedAVA 已停止重试该投递

  1. 点击 Refresh delivery logs，重新加载当前页面。

  2. 有更多结果时，使用 First page、Previous、Next 或 Last page。

  3. 打开一行以查看响应详情。

  4. 如需查看发送的 JSON，展开 View request payload。

  5. 展开 View response，查看接收端返回的确切响应正文。

    ✓ 有多个页面时，页面计数器会显示 Page X of Y。 ✓ 到达第一页或最后一页前，分页控件都会保持可用。

敏感日志详情

投递日志会显示确切的请求载荷和接收端返回的响应正文。 载荷可能包含住客数据，因此只在排查问题时展开详情。

故障排查​

页面无法加载​

你会看到： Unable to load outbound webhook settings。

解决方法：

  1. 点击 Retry。
  2. 刷新页面。
  3. 确认你所在的是正确的酒店。
  4. 如有需要，重新登录后再试。

启用 Webhook 时保存失败​

你会看到： 打开 Enabled 后保存失败。

解决方法：

  1. 输入 HMAC signing secret。
  2. 再次保存。
  3. 如果之前已经有值，请替换它，不要清空。

Send Test 一直处于禁用状态​

你会看到： 编辑页面后 Send Test 处于禁用状态。

解决方法：

  1. 先点击 Save。
  2. 等待成功消息。
  3. 再次尝试 Send Test。
  4. 确认你有设置权限。

Webhook URL 被拒绝​

你会看到： 某些目标 URL 在保存或测试时失败。

解决方法：

  1. 使用公开可访问的 HTTPS URL。
  2. 移除私有、保留、回环和站点本地地址。
  3. 使用公共接收端重新尝试。

Delivery Logs 一直为空​

你会看到： Delivery Logs 尚未显示任何行。

解决方法：

  1. 点击 Send Test。
  2. 等待一次住客验证事件。
  3. 点击 Refresh delivery logs。
  4. 如果你预期有较早的投递，请查看页面计数器和分页控件。
  5. 下一次符合条件的入住后再次检查。
  6. 如需快速跳转到较早的投递，请使用 Last page。

新的登记字段缺失​

你会看到： 登记字段未出现在 Payload Fields 中。

解决方法：

  1. 刷新 Settings → Outbound Webhook。
  2. 确认页面加载时没有报错。
  3. 对照上方的 Payload Fields Available 表检查该字段。
  4. 打开 Settings → Check-In → Registration Form。
  5. 如果住客必须提供该值，将 Show to 设置为 All guests。
  6. 保存登记表并重新加载 Webhook 页面。

可见性控制住客数据的收集。 它不会控制该字段是否出现在 Webhook 目录中。

你会看到： Webhook 不包含 marketingConsent。

解决方法：

  1. 打开 Settings → Check-In → Card & Consent。
  2. 启用正确的面向住客的营销选择加入设置。
  3. 打开 Settings → Check-In → Registration Form。
  4. 对 Marketing consent，将 Show to 设置为 All guests。
  5. 保存这两个设置页面。
  6. 确认状态卡显示 Included。
  7. 完成新的住客验证。

当住客看不到选择加入项或字段时，AVA 会省略此属性。 如果设置可见但属性仍然缺失，请联系支持团队。

仍然卡住？​

如果出现以下情况，请联系 success@vouch-technologies.com：

  • ❌ 重试后页面仍无法加载
  • ❌ 添加 HMAC 签名密钥后仍保存失败
  • ❌ 测试投递没有出现在日志中

请附上：

  • 你使用的接收端 URL
  • 你添加的任何请求头名称
  • 一张已对密钥和住客数据脱敏的 Delivery Logs 卡片截图