跳到主要内容

设置出站 Webhook 投递

快速设置

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

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

前往： Settings → Outbound Webhook

签名头

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

快速参考​

设置控制内容你会看到
Enabled打开或关闭出站 Webhook 投递保存后开关保持开启
Webhook URL投递目标 URLAVA 接受你的接收端 URL
Headers发给接收端的静态认证头保存后密钥值会保持遮罩
Payload Fields发送哪些住客字段只有勾选的字段会出现在投递中
Max attempts失败投递的重试次数数值保持在 1 到 10 之间
HMAC signing secret每次投递的载荷签名密钥启用或测试时若没有密钥，保存会被阻止
Send Test发送一次测试投递最新测试会出现在 Delivery Logs 中
Delivery Logs最近的投递状态和载荷你可以看到状态、尝试次数、HTTP 状态、响应正文、载荷详情和分页导航

开始前​

先确认这些基础项：

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

已保存的头值和签名密钥会继续隐藏。 需要替换时，点击铅笔图标即可。

发送时机​

AVA 会在住客验证成功后发送 webhook。 事件名是 guest_verified。 如果 PMS 同步失败，AVA 不会发送该 webhook。

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

配置 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 卡片中选择接收端需要的字段。 常见选项包括确认号、日期、住客联系方式、国籍、证件号和营销同意。

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

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

  3. 点击 Save。

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

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

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

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

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

  3. 输入你的 HMAC signing secret。

  4. 点击 Save。

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

替换已保存的密钥​

当头密钥或签名密钥已经存在时使用此项。 你无法查看旧值。

  1. 点击遮罩密钥旁边的铅笔图标。

  2. 输入新值。

  3. 点击 Save。

    ✓ 保存后，已保存的值仍会保持遮罩。

发送测试投递​

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

  1. 点击 Send Test。

  2. 等待成功消息。

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

    ✓ 最新的一行会显示 test delivery。

先保存

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

查看投递日志​

投递日志可帮助你检查最近 25 次尝试。 每一行都会显示投递状态、时间戳、尝试次数、HTTP 状态和详情。 你也可以打开请求载荷和响应正文。

状态含义
delivered接收端已接受投递
processingAVA 仍在处理该投递
retryingAVA 稍后会再次尝试
pendingAVA 已将该投递排队
failedAVA 已停止重试该投递
  1. 点击 Refresh delivery logs 重新加载列表。
  2. 打开某一行查看响应详情。
  3. 如需查看发送的 JSON，展开 View request payload。
详情会脱敏

日志视图中的敏感值会继续被脱敏。 只在排查问题时使用载荷详情。

故障排查​

页面无法加载​

你会看到： 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. 在下一次符合条件的入住后再次检查。

仍然卡住？​

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

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

请附上：

  • 你使用的接收端 URL
  • 你添加的任何头名称
  • Delivery Logs 卡片截图