Webhook 与 Service Token

Service Account 用于 Manifest 自动化和平台级后端任务；Webhook 用于通知业务 App 统一身份、员工状态、组织开通和客户项目上下文变化。两者都不能代替业务 App 本地授权。

Service Token

管理员创建 Service Account 后签发 iwa_ Token。明文只显示一次，数据库仅保存 hash。为自动同步 Manifest 的任务授予最小 auth.manifest.write scope，并绑定目标 App 或组织。业务 App 不使用 Service Token 远程检查本地角色或 permission；旧 auth.permission.check 不属于公开业务契约。

Token 只能保存在服务端 Secret 管理中，必须设置用途、负责人、最小 scope 和到期时间。轮换时先部署新 Token，再吊销旧 Token，并检查最近使用记录。浏览器、移动端和公共仓库不得持有 Token。

Webhook 请求

IWish-Event-Id: <uuid>
IWish-Event-Type: client_team.changed
IWish-Delivery-Id: <uuid>
IWish-Delivery-Attempt: 1
IWish-Timestamp: <unix-seconds>
IWish-Signature: v1=<hex-hmac>

使用 SDK 的 verifyIWishWebhook 或 verify_iwish_webhook，按原始请求体和时间戳校验 HMAC-SHA256。必须设置时间漂移窗口，并用 Event ID 做幂等；不能先解析再重新序列化 JSON 后验签。

Envelope 包含事件、actor、subject、组织/App 范围、cacheInvalidation 和 data。常用事件包括 user.disabled、organization.app_disabled、employee.disabled、client_project.changed 和 client_team.changed。收到事件后清理与 userIds、organizationIds、appKeys 或 clientProjectIds 相交的 session/context 缓存。

本地角色变化不由 Auth Webhook 发布，业务 App 应在自己的角色管理事务中更新本地审计并清理本地授权缓存。Auth 客户项目团队变化只刷新上下文，不得自动增加本地角色或 permission。

投递与失败

平台使用退避重试，超过上限进入死信。接收端应快速验签、落幂等记录后返回 2xx，把重任务放入队列。4xx 表示配置或签名问题，5xx 表示临时失败。管理员可查看投递、重试死信和轮换 Secret。生产 URL 必须为公网 HTTPS，禁止通配目标、跳过验签或在错误时默认放行业务请求。

验收至少覆盖正确签名、错误签名、过期时间戳、重复 Event ID、Secret 轮换、接收端超时、死信重试，以及客户团队变化不会静默扩大 App 本地权限。