订阅回调

本文介绍如何在扣子编程配置回调地址并订阅回调事件。

消息回调

订阅回调功能支持开发者通过配置回调应用实时获取扣子编程的事件通知。当智能体发布、智能体删除、智能体下架、账单生成等关键业务事件被触发时，扣子编程将向开发者指定的服务器地址发送回调消息。通过订阅对应的回调事件，开发者可以实现以下功能：

• 智能体生命周期管理
  • 订阅智能体发布回调：开发者可第一时间获取智能体发布详情，无缝衔接前端展示等后续流程。
  • 订阅智能体删除回调：开发者可以自动触发关联资源清理机制，实现智能体自动下架等能力。
• 账单动态实时追踪
  通过订阅账单推送回调，开发者可实时掌握费用流水数据，灵活实现账单自动化处理，如支出结构分析、异常费用预警等。

回调分为普通回调和渠道回调，具体说明如下：

• 普通回调：开发者在扣子编程中配置回调地址，用于接收扣子编程触发的事件通知。当订阅的事件被触发时，扣子编程会向该回调地址推送回调消息。
• 渠道回调：当自定义渠道入驻扣子编程后，开发者可以在该渠道中配置回调地址，用于接收该渠道中触发的事件通知。当订阅的事件被触发时，扣子编程会向渠道指定的回调地址推送回调消息。

回调事件

扣子编程当前提供的回调事件如下：

• 智能体发布事件
• 智能体删除回调事件
• 智能体下架回调事件
• 账单推送回调事件
• 申请插件扩容回调事件
• 插件扩容到期回调事件

使用限制

订阅普通回调

你需要在扣子编程创建回调应用并指定回调地址，用于接收扣子编程的回调事件通知。每个回调应用绑定一个回调地址。订阅事件触发时，扣子编程会向该回调地址推送消息。普通回调支持扣子官方渠道和公共渠道中的回调事件。

步骤一：创建回调应用

1. 在扣子编程左侧导航栏选择 API & SDK，在顶部选择回调管理页签。
   你也可以直接访问回调管理页面。

2. 选择普通回调管理页签，在右上角单击 +回调应用。在创建回调应用对话框中配置相关参数。参数说明如下表所示。
   

   参数	说明
   应用名称	自定义一个易于识别的回调应用的名称。
   回调地址	用于接收扣子回调的服务器地址，且需要保证该地址为公网地址，后续该回调应用订阅的所有回调，均会在触发时向该回调地址发送回调数据。
   Token	扣子编程会为每个回调应用自动生成一个 Token，不支持手动修改或删除。 当扣子编程推送回调时，会携带 Token 签发的签名，用于验证推送的回调是否属于扣子推送的合法回调。开发者验证签名的具体操作请参见接收并处理回调。

3. 配置完成后单击确认，扣子服务器会向该回调地址发送一个用于校验地址有效性的 application/json 格式的 POST 请求。
   回调的结构体示例如下：

   {
       "header": {
           "event_type": "url_verification",
           "event_id": "bee31258-469c-48a6-ae48-648161d89c79",
           "created_at": 1749116452112
       },
       "event": {
           "challenge": "988df7dc-2179-4dba-95a6-af9f40b91486"
       }
   }
   

   开发者服务器接收该请求后，需要在 3s 内将challenge值（JSON格式）原样返回给扣子编程，否则请求地址验证将失败。
   响应回调的结构体示例如下：

   {"challenge":"988df7dc-2179-4dba-95a6-af9f40b91486"}
   

步骤二：添加订阅的回调

单击订阅事件，在弹出的对话框中开启需要订阅的事件，可订阅的回调事件列表及其说明请参见回调事件。

订阅渠道回调

你可以订阅渠道回调获取对应自定义渠道中的回调信息，例如智能体发布至对应渠道、智能体从对应渠道删除、该渠道中产生的账单。

步骤一：配置回调地址

1. （可选）添加自定义渠道，具体步骤请参考步骤二：渠道管理员添加发布渠道。
   如果之前已创建自定义渠道，请忽略该步骤。

2. 在回调管理的渠道回调管理页面会展示已添加的自定义渠道，单击对应渠道卡片中的配置，配置回调地址。参数说明请参见前文创建回调应用。
   

   说明

   • 扣子个人版，仅支持展示和配置本人创建的自定义渠道的回调地址。
   • 扣子企业版（企业标准版、企业旗舰版），仅超级管理员和管理员可以配置企业中渠道的回调地址。

3. 配置完成后单击确认，扣子服务器会向该回调地址发送一个用于校验地址有效性的 application/json 格式的 POST 请求。
   回调的结构体示例如下：

   {
       "header": {
           "event_type": "url_verification",
           "event_id": "bee31258-469c-48a6-ae48-648161d89c79",
           "created_at": 1749116452112
       },
       "event": {
           "challenge": "988df7dc-2179-4dba-95a6-af9f40b91486"
       }
   }
   

   开发者服务器接收该请求后，需要在 3s 内将challenge值（JSON格式）原样返回给扣子编程，否则请求地址验证将失败。
   响应回调的结构体示例如下：

   {"challenge":"988df7dc-2179-4dba-95a6-af9f40b91486"}
   

步骤二：添加订阅的回调

单击对应渠道卡片中的订阅事件，在弹出的对话框中开启需要订阅的事件，可订阅的回调事件列表及其说明请参见回调事件。

回调事件

扣子编程当前支持的回调事件如下：

相关操作

删除回调地址

如果不再需要接收扣子编程的回调，可以删除已配置的回调地址。一旦删除，该回调应用所订阅的所有回调事件触发时，将不再向该回调地址推送通知。

取消订阅回调

如果不再需要订阅某个回调事件，可以取消订阅。一旦取消订阅，对应回调事件触发时，将不再向该回调地址推送通知。

常见问题

为什么订阅事件后，没有收到回调事件？

如果是扣子个人版，只有空间所有者创建的回调地址能收到智能体发布和智能体删除的推送通知。空间管理员和成员创建的回调地址，则不会收到其所在空间内智能体发布回调事件的推送。