# 事件目录

## 公共信封

```json
{
  "id":"evt_EXAMPLE",
  "type":"record.created",
  "api_version":"v1",
  "partner_id":"ORGANIZATION_ID",
  "created_at":"2026-09-25T03:00:00.000Z",
  "data":{"record_id":"RECORD_ID"}
}
```

`created_at` 为业务事件时间，签名头的时间为本次投递时间。所有 ID 都作为不透明字符串保存，不能假定一定是 UUID。尤其工单事件 ID 可能包含多个片段。

## 业务事件

| 事件 | 触发条件 | data |
| --- | --- | --- |
| `record.created` | 组织新增查端记录，或记录转入本组织 | `record_id` |
| `record.updated` | 本组织记录更新，包括结果更正 | `record_id` |
| `record.deleted` | 记录删除或离开本组织 | `record_id` |
| `invitation.joined` | 一次性邀请成功加入正式工单 | `ticket_id`, `invitation_id`, `status` |
| `ticket.message.created` | 组织工单新增用户或工作人员消息 | `ticket_id`, `invitation_id`, `status` |
| `ticket.status.updated` | 工单发生关闭、重开、分配等系统操作 | `ticket_id`, `invitation_id`, `status` |
| `entitlement.updated` | 组织权益授予、变更、计次或周期边界 | `game` |

工单消息事件也可能意味着 `open`/`waiting_user` 状态发生变化，因此这两种工单事件都应触发最新进度读取。系统操作不保证每次都会改变状态值。

```json
{
  "id":"evt_ticket_EXAMPLE",
  "type":"invitation.joined",
  "api_version":"v1",
  "partner_id":"ORGANIZATION_ID",
  "created_at":"2026-09-25T03:00:00.000Z",
  "data":{
    "ticket_id":"FORMAL_TICKET_ID",
    "invitation_id":"8f86690d-76d7-4e87-84d2-27b5fc8b6d41",
    "status":"open"
  }
}
```

## 验证和测试事件

- `webhook.verification`：data 为 `{ "challenge": "..." }`，必须回显。
- `webhook.test`：data 为 `{ "message": "Screenshare webhook test" }`，验签后响应 2xx。

这两种事件不需要在订阅列表中勾选，分别由验证和测试操作触发。

## 不应作出的假设

- 不会发送历史积压给刚启用的订阅，先完成初始数据同步。
- 事件载荷不包含查端结论正文、玩家远程信息或联系方式。
- `record.deleted` 不表示玩家无记录或已通过，它表示本组织应停止使用原本可见的该条记录。
- 一次业务动作可能产生多个事件。例如记录归档同时消耗次数时，可能同时产生 `record.created` 和 `entitlement.updated`。
- 消息时间和事件数量不等于扣次数量；按权益接口读取实际剩余值。
- 直接在外部工单存储中作出的操作，不应假定都有对外 Webhook；本版本覆盖网站处理流程中的事件。