凭据回调协议¶
该入口接收外部平台的校验或事件,用凭据引用匹配已保存的通道凭据,并进入回调规则。它不同于指定消息连接的入站入口。
路径与身份¶
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,但不能据文案推断实际请求平台。完整平台错误、重放和规则执行生命周期仍需后续验证。