# 凭据回调协议

该入口接收外部平台的校验或事件，用凭据引用匹配已保存的通道凭据，并进入回调规则。它不同于指定消息连接的入站入口。

## 路径与身份

```http
GET https://api.moi.matrixorigin.cn/v5/callbacks/{provider}/{workspace_id}/{credential_ref}
POST /callbacks/{provider}/{workspace_id}/{credential_ref}
```

路径来自当前部署和通道实例配置。credential_ref是凭据引用，不是connection_id、PAT或公开Web应用token。handler没有产品身份包装，但service仍检查凭据所在工作区、平台/工具绑定、active状态、到期及平台协议凭据。

不为这两条接收路径新增普通产品SDK“调用回调”方法。调用方是配置好的外部平台，用户通过已有实例、凭据与回调规则管理能力配置；

## GET校验

当前GET仅支持企业微信。读取timestamp、nonce、echostr、signature及msg_signature，按已保存的回调Token/加密配置验证挑战，返回平台需要的原始响应。provider是路径参数不代表所有平台都支持GET验证。

挑战成功只证明该校验通过，不表示规则已匹配、智能体任务已执行或消息已送回平台。

## POST事件

所查事件分支包括企业微信、GitHub、飞书、Slack和Telegram，各自按平台凭据和消息协议处理。GitHub使用签名后的原始body并识别事件/投递ID；Slack的签名校验包含时间窗口；其他平台有各自挑战/加密/密钥约束，不能用普通PAT替代。

认证后的事件进入回调规则及对应目标；普通平台HTTP确认可以是纯文本或平台JSON，不使用固定code=OK包。事件不匹配或挑战请求可确认后不触发任务。smart-bot凭据在旧事件sink路径被拒绝，不把它与消息入口的企业微信智能机器人分支互换。

## 大小与错误

该POST handler读到4 MiB再加一字节判断超限，超限走无效输入400/code2。它与消息入口的2 MiB限制和413结果不同，不能共用一个固定回调大小承诺。网关还可能另有限制，实际环境待核。

错误包为数值code、message和可能含request_id的details；参数400/2、签名或解密401/6、凭据不存在404/3、未就绪424/15、事件sink未配置503/15等分别处理。部分通用错误文案仍写wecom，但不能据文案推断实际请求平台。完整平台错误、重放和规则执行生命周期仍需后续验证。
