> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

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

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

* [智能体发布事件](/developer_guides/agent_callback_messages#fd769133)
* [智能体删除回调事件](/developer_guides/agent_delete_callback_messages)
* [智能体下架回调事件](/developer_guides/agent_unpublished_callback_messages)
* [账单推送回调事件](/developer_guides/billing_callback_message)
* [申请插件扩容回调事件](/developer_guides/benefit_plugin_scale_requested)
* [插件扩容到期回调事件](/developer_guides/benefit_plugin_scale_expired)

## 使用限制 {#47628aaf}
<!-- @cols-width: 115,436,302 -->
| | | | \
|**回调事件** |**扣子个人版** |**扣子企业版** |\
| | |**（企业标准版、企业旗舰版）** |
|---|---|---|
| | | | \
|账单推送 |* 个人免费版：不支持订阅账单推送事件。 |\
| |* 个人进阶版等其他个人版：任意用户均可订阅自己的账单推送事件。 |仅超级管理员和管理员可订阅，统一接收企业中的所有回调消息。 |
| | | | \
|其他事件 |* **普通回调**：仅空间所有者可订阅，统一接收工作空间中除**账单推送事件**以外的所有回调消息。 |\
| |* **渠道回调**：仅自定义渠道的创建者可订阅，统一接收该渠道中除**账单推送事件**以外的所有回调消息。 |仅超级管理员和管理员可订阅，统一接收企业中的所有回调消息。 |
| | | | \
|申请插件扩容 |\
|插件扩容到期 |不支持。 |* 仅**三方付费插件的开发者**可订阅，统一接收插件扩容事件。 |\
| | |* **套餐限制**：**企业旗舰版**。 |\
| | |* 仅支持普通回调，不支持渠道回调。 |

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

1. 在扣子编程左侧导航栏选择 **API & SDK**，在顶部选择**回调管理**页签。
   你也可以直接访问[回调管理](https://code.coze.cn/playground)页面。
2. 选择**普通回调管理**页签，在右上角单击 **+回调应用**。在**创建回调应用**对话框中配置相关参数。参数说明如下表所示。
   ![Image=600x396](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/4fa4419cc7f44dd9a1565d800dab54c7~tplv-goo7wpa0wc-image.image)
   <!-- @cols-width: 100,611 -->
   | | | \
   |**参数** |**说明** |
   |---|---|
   | | | \
   |应用名称 |自定义一个易于识别的回调应用的名称。 |
   | | | \
   |回调地址 |用于接收扣子回调的服务器地址，且需要保证该地址为公网地址，后续该回调应用订阅的所有回调，均会在触发时向该回调地址发送回调数据。 |
   | | | \
   |Token |扣子编程会为每个回调应用自动生成一个 Token，不支持手动修改或删除。 |\
   | |当扣子编程推送回调时，会携带 Token 签发的签名，用于验证推送的回调是否属于扣子推送的合法回调。开发者验证签名的具体操作请参见[接收并处理回调](/dev_how_to_guides/receive_handle_callbacks)。 |

3. 配置完成后单击**确认**，扣子服务器会向该回调地址发送一个用于校验地址有效性的 `application/json` 格式的 POST 请求。
   回调的结构体示例如下：
   ```JSON
   {
       "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格式）原样返回给扣子编程，否则请求地址验证将失败。
   响应回调的结构体示例如下：
   ```JSON
   {"challenge":"988df7dc-2179-4dba-95a6-af9f40b91486"}
   ```


### 步骤二：添加订阅的回调 {#fe2ee707}
单击**订阅事件**，在弹出的对话框中开启需要订阅的事件，可订阅的回调事件列表及其说明请参见[回调事件](/dev_how_to_guides/add_callback#e63c85cc)。
![Image=600x428](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/457f0408b78f4c748a194342e4f32e5f~tplv-goo7wpa0wc-image.image)
## 订阅渠道回调 {#72098317}
你可以订阅渠道回调获取对应**自定义渠道**中的回调信息，例如智能体发布至对应渠道、智能体从对应渠道删除、该渠道中产生的账单。
### 步骤一：配置回调地址 {#21a3fe45}

1. （可选）添加自定义渠道，具体步骤请参考[步骤二：渠道管理员添加发布渠道](/dev_how_to_guides/configure_custom_channel2#debea935)。
   如果之前已创建自定义渠道，请忽略该步骤。
2. 在[回调管理](https://code.coze.cn/playground)的**渠道回调管理**页面会展示已添加的自定义渠道，单击对应渠道卡片中的**配置**，配置回调地址。参数说明请参见前文[创建回调应用](/dev_how_to_guides/add_callback#716c8182)。
   ![Image=600x357](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/7e43477752204bbdb3782e889ccbe385~tplv-goo7wpa0wc-image.image)
   :::tip 说明
   * 扣子个人版，仅支持展示和配置本人创建的自定义渠道的回调地址。
   * 扣子企业版（企业标准版、企业旗舰版），仅超级管理员和管理员可以配置企业中渠道的回调地址。
   :::
3. 配置完成后单击**确认**，扣子服务器会向该回调地址发送一个用于校验地址有效性的 `application/json` 格式的 POST 请求。
   回调的结构体示例如下：
   ```JSON
   {
       "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格式）原样返回给扣子编程，否则请求地址验证将失败。
   响应回调的结构体示例如下：
   ```JSON
   {"challenge":"988df7dc-2179-4dba-95a6-af9f40b91486"}
   ```


### 步骤二：添加订阅的回调 {#4f87699b}
单击对应渠道卡片中的**订阅事件**，在弹出的对话框中开启需要订阅的事件，可订阅的回调事件列表及其说明请参见[回调事件](/dev_how_to_guides/add_callback#e63c85cc)。
![Image=500x226](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/d1c90216251b48f0a649d0453647744c~tplv-goo7wpa0wc-image.image)
## 回调事件 {#e63c85cc}
扣子编程当前支持的回调事件如下：
<!-- @cols-width: 109,100,249,265,141 -->
| || | | | \
|**回调事件** | |**扣子个人版** |**扣子企业版** |**相关文档** |
|---|---|---|---|---|
| | | | | | \
|智能体发布 |普通回调 |仅**空间所有者**可订阅，当工作空间中任意智能体被发布至扣子编程官方渠道或公共渠道时，对应的回调地址会收到智能体发布回调事件。 |仅**超级管理员和管理员**可订阅，当企业内任意智能体被发布至扣子编程官方渠道或公共渠道时，对应的回调地址会收到智能体发布回调事件。 |[智能体发布事件](/developer_guides/agent_callback_messages#fd769133) |
|^^| | | |^^| \
| |渠道回调 |仅**自定义渠道创建者**可订阅，当智能体发布至该自定义渠道时，对应的回调地址会收到智能体发布回调事件。 |仅**超级管理员和管理员**可订阅，当智能体发布至该自定义渠道时，对应的回调地址会收到智能体发布回调事件。 | |
| | | | | | \
|智能体删除 |普通回调 |仅**空间所有者**可订阅，当工作空间中任意智能体被删除时，对应的回调地址会收到智能体删除回调事件。 |仅**超级管理员和管理员**可订阅，当企业内任意智能体被删除时，对应的回调地址会收到智能体删除回调事件。 | |\
| | | | |[智能体删除回调事件](/developer_guides/agent_delete_callback_messages) |
|^^| | | |^^| \
| |渠道回调 |仅**自定义渠道创建者**可订阅，当该渠道中的智能体被删除时，对应的回调地址会收到智能体删除回调事件。 |仅**超级管理员和管理员**可订阅，当自定义渠道中的智能体被删除时，对应的回调地址会收到智能体删除回调事件。 | |
| | | | | | \
| |\
|智能体下架 |普通回调 |仅**空间所有者**可订阅，当工作空间中任意智能体被下架时，对应的回调地址会收到智能体下架回调事件。 |仅**超级管理员和管理员**可订阅，当企业内任意智能体被下架时，对应的回调地址会收到智能体下架回调事件。 |[智能体下架回调事件](/developer_guides/agent_unpublished_callback_messages) |
|^^| | | |^^| \
| |渠道回调 |仅**自定义渠道创建者**可订阅，当该渠道中的智能体被下架时，对应的回调地址会收到智能体下架回调事件。 |仅**超级管理员和管理员**可订阅，当自定义渠道中的智能体被下架时，对应的回调地址会收到智能体下架回调事件。 | |
| | | | | | \
|账单推送 |普通回调/渠道回调 |除个人免费版以外，其他个人版套餐的空间中任意成员均可订阅本人的账单。 |仅超级管理员和管理员可订阅，统一接收企业中的所有账单回调。 |[账单推送回调事件](/developer_guides/billing_callback_message) |
| | | | | | \
|申请插件扩容 |\
|插件扩容到期 |普通回调 |不支持。 |仅**三方付费插件的开发者**可订阅，统一接收插件扩容事件。 |* [申请插件扩容回调事件](/developer_guides/benefit_plugin_scale_requested) |\
| | | | |* [插件扩容到期回调事件](/developer_guides/benefit_plugin_scale_expired) |

## 相关操作 {#55902b35}
### 删除回调地址 {#52c42021}
如果不再需要接收扣子编程的回调，可以删除已配置的回调地址。一旦删除，该回调应用所订阅的所有回调事件触发时，将不再向该回调地址推送通知。
![Image=300x313](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/09486d2b7c4b4bbe9bcd786a9003aec5~tplv-goo7wpa0wc-image.image)
### 取消订阅回调 {#9b78ec29}
如果不再需要订阅某个回调事件，可以取消订阅。一旦取消订阅，对应回调事件触发时，将不再向该回调地址推送通知。
![Image=600x428](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/457f0408b78f4c748a194342e4f32e5f~tplv-goo7wpa0wc-image.image)
## 常见问题 {#2a52eb87}
### 为什么订阅事件后，没有收到回调事件？ {#7d3b641e}
如果是扣子个人版，只有**空间所有者创建的回调地址**能收到智能体发布和智能体删除的推送通知。空间管理员和成员创建的回调地址，则不会收到其所在空间内智能体发布回调事件的推送。