回调服务

回调把服务端事件（消息路由、用户状态、群/聊天室变更、审核结果、机器人事件等）异步 POST 到应用服务器。控制台负责配置地址与订阅事件、查看投递日志、重试失败投递。

概念​

  • 签名：X-IM-Signature = hex(hmac_sha256(secret, timestamp + "." + nonce + "." + rawBody))，另有 X-IM-Timestamp、X-IM-Nonce。
  • 重试：默认最多 3 次、退避 1s（可在配置中调整为 1-5 次 / 1000-60000ms）。
  • 单次投递超时 5 秒，请求体上限 256KB；投递日志内存上限 10000 条。
  • secret 读取时脱敏（**** + 末四位），设置时长度 8-128。
  • CB01 同步回调（syncEnabled）会阻塞消息投递直到应用决策或超时（100-2000ms，默认 500ms）。

前置条件​

  • 服务端已启动（默认 http://127.0.0.1:8080），控制台入口 http://127.0.0.1:8080/console/#callbacks。
  • 已设置 X-Admin-Secret（默认 dev-admin；控制台会保存在浏览器 localStorage 的 im.admin.secret）。
  • 已创建应用并在控制台顶部选中应用（模块接口路径都带 {appkey}）。
  • 回调 URL 必须 http(s) 且可从服务端访问；启用时 URL 必填。

步骤​

  1. 配置回调

    提交 enabled、url、events；secret 为空表示沿用旧值。

  2. 发送测试
    callbacks/test 会真实投递一条事件并写入投递日志（未开通回调服务返回 1024）。
  3. 查看与重试投递

    按 status=failed 过滤；用 deliveryId 单条重试。

参数表​

操作方法与路径请求体 / 参数
配置查询GET /api/admin/apps/{appkey}/callbacks—
配置设置POST /api/admin/apps/{appkey}/callbacks{enabled,url,events,secret?,retry?,syncEnabled?,syncTimeoutMs?,syncDefaultAction?}
投递日志GET /api/admin/apps/{appkey}/callbacks/deliverieseventType、status（pending/success/failed/dropped）、from、to、offset、limit
重试POST /api/admin/apps/{appkey}/callbacks/deliveries/{delivery_id}/retry—
测试投递POST /api/admin/apps/{appkey}/callbacks/test{eventType?,payload?}

示例​

配置 → 测试 → 查失败 → 重试​

Shell
curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/callbacks" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"enabled":true,"url":"https://example.com/im/callback","secret":"callback-secret","events":["message.routed","message.offline","message.audit_result"],"retry":{"maxAttempts":3,"backoffMs":1000}}'

curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/callbacks/test" \
  -H 'X-Admin-Secret: dev-admin' \
  -H 'content-type: application/json' \
  -d '{"eventType":"test.ping","payload":{"hello":"world"}}'

curl -sS -X GET "http://127.0.0.1:8080/api/admin/apps/demo/callbacks/deliveries?status=failed&limit=20" \
  -H 'X-Admin-Secret: dev-admin'

# 用 items[].deliveryId
curl -sS -X POST "http://127.0.0.1:8080/api/admin/apps/demo/callbacks/deliveries/dlv_3001/retry" \
  -H 'X-Admin-Secret: dev-admin'

常见问题​

配置保存后 secret 显示 ****，怎么确认？​

服务端只返回脱敏值。需要更换时直接提交新 secret（8-128 字符）；不要试图读取明文。

投递一直失败怎么排查？​

看 error 与 responseCode；确认 URL 可达、HTTPS 证书有效、5 秒内响应、请求体未超 256KB。可用 /docs/guides/troubleshooting 的回调排查步骤。

同步回调超时会丢消息吗？​

不会。同步回调失败按 syncDefaultAction 处理（默认 pass 放行，可配 block 拒绝），不会因超时丢消息。

未开通 callbacks 服务会怎样？​

事件不入队（直接丢弃），配置/投递类 Open API 返回 1021；控制台测试投递返回 1024。

相关链接​