配置回调地址

登记接收事件的地址。青鸾不会把你的地址交给能力层：能力层只认我方接收器，事件到达后由我方转发给你，并附上青鸾签名。

POST/qingluan/instances/set-callback

在线调试鉴权与基础约定

接口说明

登记接收事件的地址。青鸾不会把你的地址交给能力层：能力层只认我方接收器，事件到达后由我方转发给你，并附上青鸾签名。

验签：用返回的 callback_secret 计算 HMAC-SHA256(secret, "{X-Qingluan-Timestamp}." + 原始请求体)，与请求头 X-Qingluan-Signature 比对。

你会收到的包体：{appid, event_type, events}；事件类型在 event_type 字段里，不在任何 HTTP 头上。

⚠️ 本接口是青鸾自有接口，返回青鸾信封 {ok, code, message, request_id, data}，与数据面透传接口的原样返回不同。

请求参数

请求体必填。通过 QL-Key 请求头携带 APIKey。

Content-Type：application/json

appidstring必填

青鸾实例 ID，形如 we_xxxxxxxxxxxxxxx。在开发者控制台「实例与回调」扫码上号后获得。

字段示例："we_xxxxxxxxxxxxxxx"

callbackUrlstring必填

你的接收地址，必须是 http(s) 开头的公网地址。

字段示例："https://your.app/qingluan/callback"

响应与结果确认

本接口使用青鸾信封 {ok, code, message, request_id, data}。按返回的状态与说明处理结果，保存回调验签所需的 callback_secret。

响应字段与 HTTP 状态

HTTP 200

登记成功（青鸾信封）

application/json

查看响应字段定义

okboolean可选

字段示例：true

codeinteger可选

字段示例：0

messagestring可选

字段示例："success"

request_idstring可选

本次调用的追踪 ID，排查问题时提供它。

字段示例："ql_7a44f0c1e2b34d56a8f9"

dataobject可选

appidstring可选

callback_urlstring可选

callback_secretstring可选

验签密钥，仅在此返回，请妥善保存。

字段示例："whsec_xxxxxxxxxxxxxxxx"

HTTP 400

缺少 appid，或 callbackUrl 不是 http(s) 地址

HTTP 404

appid 不存在或无权访问

HTTP 502

登记失败，请稍后重试

请求示例

请求示例 · JSON

{
  "appid": "we_xxxxxxxxxxxxxxx",
  "callbackUrl": "https://your.app/qingluan/callback"
}

响应示例

HTTP 200 响应示例 · JSON

{
  "ok": true,
  "code": 0,
  "message": "success",
  "request_id": "ql_7a44f0c1e2b34d56a8f9",
  "data": {
    "appid": "we_xxxxxxxxxxxxxxx",
    "callback_url": "https://your.app/qingluan/callback",
    "callback_secret": "whsec_xxxxxxxxxxxxxxxx"
  }
}

本接口使用青鸾信封 {ok, code, message, request_id, data}。按返回的状态与说明处理结果，保存回调验签所需的 callback_secret。