English

Partner API — Enquiry and Offer Webhooks

Authorised partners receive signed, minimal notifications for viewing requests, thread messages and offers, then fetch current details through the existing Partner API. Transactional capture, frozen consent and enrollment references, fresh key authority and bounded HTTPS delivery preserve privacy and prevent delayed work from following newly granted access.

  • Predecessor Partner API foundation, shared landlord scope/consent primitives, and the enquiries-and-offers API contract
  • Status Approved

View source markdown ↗ generated by openai-codex/gpt-6.1-sol · diagrams mermaid

概览

获授权的合作伙伴在看房请求、消息或报价发生变化时收到签名通知,再通过现有 Partner API 获取当前详情。Go 事务型 outbox 捕获每一次符合条件的业务变化;后台 worker 仅在原有登记、授权同意及当前读取权限仍然有效时投递。

  • 受众现有受管理合作伙伴
  • 界面现有合作伙伴管理详情页
  • 捕获Go + PostgreSQL 事务
  • 权限依据Bun 密钥元数据 + 房东授权同意

成功标准是原子化、持久化捕获,在业务请求之外投递签名的最小通知,按界限重试,由合作伙伴按事件 ID 去重并执行获授权的 API 读取。房东授权同意、密钥权限上限、live 模式隔离及合作伙伴创建房产的边界始终生效。通知覆盖租客、房东、合作伙伴(包括其自身操作)及自动化;它不是审计流,也不是事件发生时的资源快照。

决策与取舍

决策已确定的方案
范围与载荷仅限咨询与报价;使用最小、带版本的标识符,通过 API 读取详情。
操作主体覆盖所有主体,包括订阅合作伙伴及自动化业务变化。
配置每个合作伙伴一个由管理员管理的回调;不设事件过滤器。
访问权限指定的 enquiries:read 密钥、当前房东读取授权及现有资源可见性。
投递Go worker 执行有界的至少一次尝试,使用公共 HTTPS、HMAC-SHA256 和加密密钥。
恢复与检查仅自动重试;终态任务不会复活。近期结果保留 30 天;待处理/租约中的任务受到保护。

不新增 broker 的持久化捕获

使用 PostgreSQL 事务型 outbox 记录和有界 Go worker。

业务变更与事件一并提交,避免提交与入队之间丢失通知,同时无需运维新的消息服务。

否决:提交后入队(崩溃时可能丢失);outbox 加外部 broker(增加服务与运维负担)。租赁邮件队列不能充当台账:NotificationEventRepository.Enqueue 按主体类型、主体 ID、种类及收件人去重,而反复发生的业务变化需要各自独立的 ID。Bun 内存事件总线无法为 Go 业务变更提供持久化捕获。

基础与依赖

依赖 Partner API 基础、共享房东范围/授权原语,以及咨询与报价设计和对应的后端/前端 OpenSpec 变更。规划产物不代表这些前置条件已实现。复用已交付的范围/可见性接口及非目标;Partner API 中的报价仍为只读。

已观察到的集成边界与准确代码引用
状态与消息
backend/go/internal/modules/rental/domain/entity/viewing_request.go 定义看房状态/转换及会话消息;offer.go 定义报价状态/转换及条款。
业务变更归属
backend/go/internal/modules/rental/application/usecase/viewing_request.go 负责请求创建/操作及普通消息;创建流程的 WithTx 已接受租赁事务执行器。持久化的系统消息及批量业务变化路径也在范围内;仅挂接 HTTP 不足以覆盖。
合作伙伴范围
backend/go/internal/modules/rental/adapter/inbound/http/partner_routes.go 组合合作伙伴认证、密钥权限上限、授权及 live 房东范围。
密钥权威来源
backend/go/internal/api/http/middleware/better_auth_validator.go 将密钥验证交由 Bun,绝不直接读取哈希或 API 密钥表。backend/bun/apps/monolith/src/api-gateway/routes/admin-partner-keys.routes.ts 负责合作伙伴密钥管理及净化元数据;使用内部边界,不重复实现 Better Auth 归属逻辑。
密钥加密
backend/go/internal/shared/infrastructure/crypto/aes_gcm.go 提供共享 AES-256-GCM。
网络安全
backend/go/internal/shared/infrastructure/safefetch/dial.go 提供公共地址检查、已检查 IP 拨号及无代理传输。复用其拨号策略,而非 fetch.go 中的图片获取封装。

公开事件契约

事件资源捕获触发条件
viewing_request.createdviewing_request新的看房请求被持久化。
viewing_request.updatedviewing_request业务状态或建议/确认时间发生变化,即使状态值未变。
message.createdmessage普通、初始或系统生成的会话消息被持久化。
offer.createdoffer新报价被持久化。
offer.updatedoffer状态或条款发生变化,即使状态值未变。

每次资源变化产生一个事件,而不是每个 HTTP 请求一个事件:请求加初始消息产生两个创建事件;看房操作加系统消息产生一个更新事件和一个消息事件。批量操作仅对实际发生变化的资源发出事件。不新增业务转换或消息生成。

不可变事件封套

每次回调是一个 UTF-8 JSON 对象,只序列化一次,并为每次尝试保留完全一致的字节。绝不从当前状态重建,也不添加每次尝试特有的字段。

字段契约
id唯一事件 UUID,一次分配,重试期间不变。
type上述五个事件名称之一。
schema_version整数 1。
occurred_at随业务变更记录的 UTC RFC 3339 时间;不是发送时间或排序序号。
landlord_id现有 Partner API 房东用户标识符,以字符串表示。
resource.typeviewing_request、message 或 offer,与 type 一致。
resource.id现有资源标识符,以字符串表示。
resource.viewing_request_id消息/报价必填父请求标识;看房请求省略。

不包含租客标识、姓名、联系方式、消息正文、看房时间、报价条款、操作主体详情、内部路由字段及授权修订号。合作伙伴获取看房/报价详情或对应消息会话;不新增单条消息端点。

配置与授权

每个合作伙伴有一个 HTTPS 端点、启用状态、指定 API 密钥 ID 和签名密钥。密钥必须归属该合作伙伴、有效且未过期,并允许咨询读取;仅写入权限不足。单调递增的配置代次标识登记:启用/禁用、URL 变更、重新绑定和轮换均使旧任务失效。重复使用 URL 或密钥绝不会恢复旧任务。

持久化捕获绝不在事务内等待 Bun。冻结的候选对象尚不能投递;每次发送前都须重新确认当前权限。
持久化捕获绝不在事务内等待 Bun。冻结的候选对象尚不能投递;每次发送前都须重新确认当前权限。

按房产来源、房东及 live 模式边界捕获有效合作伙伴、已启用端点及有效读取授权。保存端点代次、指定密钥 ID、授权 ID 和修订号。绝不将新启用登记或新批准授权附加到旧事件。只有符合条件的候选对象成为投递记录;确定性拒绝直接完成抑制,不进行外部 I/O;临时查询失败则保留到期的持久化任务。

每次尝试前的访问关卡

四层读取限制:合作伙伴密钥、房东授权、live 来源范围及消息会话归属。 合作伙伴密钥 房东授权同意 live 来源范围 会话归属
所有适用关卡取交集,互不替代。消息归属进一步要求匹配捕获的父会话。进入这些关卡前,端点须仍启用并匹配捕获的代次/密钥绑定,合作伙伴也须有效。
  1. 端点已启用,匹配捕获的代次及指定密钥。
  2. 合作伙伴有效;新查询的 Bun 权威密钥归属同一合作伙伴、有效且未过期,并具有 enquiries:read。
  3. 捕获的授权仍有效,具有 enquiries:read 且同意修订号完全一致。
  4. 资源在明确的房东/live/合作伙伴创建房产范围内可读;消息属于捕获的父会话。

不新增 webhook 授权范围、全房产授权、写入隐含读取或无限制读取兜底。已归档历史沿用现有咨询可见性,不新增一律排除归档资源的规则。

Bun 仅通过已认证内部查询返回密钥 ID/所有者/配置、权限、启用状态及到期时间。明确区分不存在/无效/外部归属/非合作伙伴配置的密钥与服务故障。Go 不接收或存储原始令牌/哈希,也绝不查询 Better Auth 表;后台查询不冒充普通 API 密钥请求,不消耗请求配额。

持久化与原子性

租赁模块所属记录保存的数据
端点合作伙伴、URL、密钥 ID、启用状态、代次、加密密钥密文/nonce 及常规时间戳。
Outbox事件 ID/类型/时间、准确载荷字节、资源/房东/父请求可见性标识、冻结的受众登记/授权引用、路由结果及时间戳。
投递事件/登记引用;待处理、在途、已投递、失败或已抑制状态;尝试次数;上次/下次尝试时间;租约令牌/到期时间;最近 HTTP 状态;净化原因及终态时间戳。

事件/登记组合的唯一约束避免路由重试时产生重复投递。不可变事件 UUID 标识一次变化,而非资源/类型自然键。诊断存于投递记录,不新增独立分析或响应正文存储。

仅按需扩展现有租赁事务执行器/仓库集合,使选定变化和 outbox 插入同事务提交。覆盖初始与系统消息、定时状态转换、批量更新及普通用例。Outbox 持久化失败必须回滚业务变更;禁止提交后捕获或吞掉入队错误。

传输与签名

仅允许公共 HTTPS

  • HTTPS POST、验证证书、带主机的绝对 URL、总超时 10 秒。拒绝嵌入凭据和片段。
  • 禁止重定向、API 凭据、cookie、环境代理或关闭 TLS 验证。
  • 配置时验证主机名,连接时验证公共地址。阻止私有、回环、链路本地、其他禁止地址及公私混合 DNS。
  • 直接连接已检查 IP,不二次解析主机名,并保留主机名/证书验证。连接复用不得绕过已验证端点/代次;新连接使用受保护拨号器。
  • 使用 safefetch.Dialer,而非图片获取 API/重定向策略。可使用受控测试解析器/传输;交付代码禁止私有网络/TLS 绕过。
  • 仅检查状态;限制响应排空并关闭响应。绝不保存/记录响应正文、URL 凭据、cookie 或签名材料。

准确字节签名契约

内容类型
Content-Type: application/json
事件标识
Webhook-Id:封套中的事件 UUID。
尝试时间
Webhook-Timestamp:本次尝试的十进制 Unix 秒。
签名
Webhook-Signature: v1=<lowercase hexadecimal HMAC-SHA256 digest>
签名字节
用原始 32 字节密钥对 <timestamp>.<exact JSON body> 签名;时间戳与请求头一致。重试保留正文/ID,并刷新时间/签名。
  1. 接受前验证。 解码 base64 密钥;以常数时间比较 HMAC;要求请求头/正文 ID 一致,时间戳在接收方时钟的五分钟内。双方均需正常运行的 UTC 时钟。
  2. 持久化去重。 使用事件 ID;确认丢失或 worker 崩溃后,同一事件可能再次到达。
  3. 持久化接受后再确认。 只有持久化接受后才能返回成功;业务处理随后可继续异步进行。

签名密钥生命周期

生成 32 个加密安全随机字节,在创建或轮换时仅披露一次 base64 编码。使用共享 AES-256-GCM、全新 nonce 和通过后端密钥/配置机制提供的包装密钥加密原始字节。

普通读取仅显示密钥是否存在。URL、日志/审计、诊断或历史均不得出现签名密钥值;审计管理员操作/主体,但不记录密钥。轮换在禁用状态下立即替换密钥:没有双密钥重叠,也没有再次查看密钥的端点。

Worker、重试与结果

扫描
每五秒一次,有界批次和并发;回调 I/O 不占用事务。
领取
60 秒租约及唯一令牌;到期允许恢复,完成更新须匹配当前令牌,拒绝过时 worker。
期限
自 occurred_at 起 24 小时,包括路由/权限服务故障时间;绝不延长。
尝试上限
最多八次外部尝试;符合条件的已提交任务首次被领取时发送。
按时间比例显示重试延迟:30 秒、2 分钟、10 分钟、1 小时、3 小时、6 小时和 12 小时。 重试 1 · 30s 重试 2 · 2m 重试 3 · 10m 重试 4 · 1h 重试 5 · 3h 重试 6 · 6h 重试 7 · 12h 0h12h
不均匀重试延迟使用同一时间比例:30 秒、2 分钟、10 分钟、1 小时、3 小时、6 小时、12 小时。每次延迟从上一次尝试完成时开始,而非事件捕获时。尝试耗尽或事件达到 24 小时即失败,以先发生者为准;这些是固定策略值。
观察到的结果处理
任何 2xx终态已投递;忽略响应内容。
超时、临时网络故障、408、429、5xx在尝试/时限内重试。
其他 4xx 或任何 3xx终态失败;绝不跟随重定向。
不安全目的地址终态失败,不建立被阻止的连接。
确定的访问/登记丢失终态已抑制,不发送。
临时权限服务/数据库故障延后检查 30 秒;不消耗外部尝试次数,原期限仍生效。

调用发送器前持久化递增尝试次数,包括 DNS/连接/响应故障,保证崩溃不会重置上限。本地资格服务故障不计数。首次发送前过期的待处理任务,以过期原因为失败。

终态不回到待处理。领取令牌拒绝过时完成更新,但确认丢失仍可能导致再次接受相同投递;发送前会重新检查权限。
终态不回到待处理。领取令牌拒绝过时完成更新,但确认丢失仍可能导致再次接受相同投递;发送前会重新检查权限。

管理生命周期与保留策略

在现有合作伙伴详情页新增 webhook 区域,遵循其管理员权限、样式、本地化、密钥选择及请求约定,不另建仪表盘或门户。

  1. 保存禁用配置。 验证 HTTPS URL,并选择有效、未过期、同一合作伙伴且可读取的密钥。
  2. 仅披露一次。 生成/保存密钥,一次性显示 base64 编码;端点初始为禁用。
  3. 安装后明确启用。 将密钥交给合作伙伴,仅在接收方准备好后启用。
  4. 变更登记前先禁用。 URL 编辑、密钥重新绑定及轮换均须禁用。轮换/分享/安装后,再明确启用。

安全的分页历史

近期历史限于该合作伙伴,且有界、分页。显示事件类型/ID、状态、外部尝试次数、创建/上次尝试/终态时间、待处理的下次重试时间、最近 HTTP 状态及净化失败/抑制原因。绝不显示响应正文或密钥。不提供重投按钮、合成测试事件或分析。

终态保留

终态记录自终态时间戳起保留 30 天。安全删除终态投递/路由记录及未被引用的不可变事件;保护待处理、租约中及仍被引用的任务。无受众事件须有终态路由结果,避免无限积累。保留策略独立于 24 小时期限,不改变端点配置或审计策略。

归属与交付边界

Go 租赁后端

原子捕获、端点/管理 API、候选/投递持久化、worker/租约/重试、访问检查、签名、安全传输、保留及后端验证。复用租赁 ports/adapters 与模块生命周期;不新增独立 webhook 服务。

Bun 权威来源

经现有已认证内部监听器约定提供权威合作伙伴密钥元数据:所有者、配置、权限、启用状态及到期时间。无公开 webhook 管理,也不共享原始密钥。

管理界面与文档

端点/密钥表单、密钥披露、明确生命周期操作、警告及近期历史。记录封套、签名、确认/去重、重试/到期、授权/来源边界、启用/轮换及对账。

验证与验收

永久测试覆盖使用者可见行为、边界、转换和错误,不测试源码字符串、复制的权限范围数组、辅助函数转发或界面措辞。

  1. 捕获。 验证所有主体下的五种类型、初始/系统消息及批量变化;资源/outbox 原子提交与强制 outbox 失败回滚。重放、无变化、记账、拒绝和回滚写入均无事件。
  2. 受众/授权。 自有合作伙伴的 live 资源登记;错误房东/模式/来源、缺失读取授权或禁用/未配置端点不登记。新端点/授权绝不获得旧事件。
  3. 当前访问。 外部归属、仅写入、过期、禁用或缺失密钥不能发送。授权替换/撤销、密钥丢失、代次变化及资源不可见永久抑制待处理任务。限定范围读取器强制资源/会话归属。
  4. Bun 隔离。 已认证内部查询不返回令牌/哈希;拒绝外部归属/非合作伙伴配置密钥。故障仍让业务变更提交、事件延后,绝不授予访问或消耗尝试。
  5. 安全。 验证准确字节上的真实签名;检测篡改、ID 不一致、过期时间戳及重复处理。通过受控传输/解析器验证 TLS、拒绝重定向、私有/混合 DNS、重绑定、禁用代理及有界响应。
  6. 投递。 确定性时钟和持久化状态验证重试计划、八次上限、24 小时到期、分类、并发领取、崩溃恢复、过时令牌拒绝及接受后崩溃的重复语义。
  7. 生命周期/历史。 验证加密/篡改处理与一次披露;读取/日志/历史绝不泄露密钥。禁用/轮换/重新绑定使旧任务失效。30 天清理仅删除终态/无引用数据,绝不删除待处理/租约中任务。
  8. 浏览器验证。 按获准浏览器流程,在常规/窄屏宽度操作真实表单、密钥选择、披露、控件/警告和分页历史;验证代表性的实际本地化渲染,不做措辞测试。
  9. 运行时验证。 使用真实获批读取授权与接收方,触发咨询变化,观察签名 HTTPS 接收及获授权 API 读取,演示临时失败重试,再于待发送前撤销权限并观察抑制。检查持久化结果,不止验证 mock 转发。
  10. 回归/文档。 保持租赁流程、v1/Partner 隐私/幂等性及管理/Bun 认证不变。记录五种类型/字段、准确签名字节/请求头、去重/确认、有界失败、禁用期间对账及访问限制。

风险、非目标与评审关卡

  • 确认丢失导致重复:接收方必须去重。
  • 授权修订号/登记截断防止旧任务跟随新权限或 URL;仅有效状态不足。
  • 跨服务权限故障延后持久化任务;Go 不得通过读取 Better Auth 表绕过 Bun。
  • 禁用/轮换抑制旧任务并丢失期间通知;API 对账是有意的设计。
  • 批量/系统消息变更需要原子捕获;仅 HTTP 挂接会遗漏。
  • 新鲜访问检查不能撤回在途发送或已披露标识;最小载荷降低而非消除风险。
  • 长期接收方/worker/权限服务故障耗尽固定重试或时限;历史展示失败,不暗中承诺最终投递。
  • 包装密钥配置和正常接收方是启用前提;禁止明文/无签名兜底。

明确非目标

开发者门户/自助服务;房产/房源/租约/支付/交接事件类别;完整资源快照;排除特定操作主体;事件过滤器;多端点或按房东配置端点;私有回调;绕过 TLS;外部 broker;严格排序;恰好一次投递;历史补发/重放;人工重投;合成测试工具;分析仪表盘;新报价写入;无关重构。