EvolutionAPI Webhook Base64 功能异常分析与解决方案

问题背景

在EvolutionAPI项目中，从版本1.8.1升级到2.1.0后，用户报告了一个关于Webhook Base64功能的严重问题。该功能在保存设置后无法保持启用状态，页面刷新后会自动恢复为禁用状态。类似的问题也出现在"webhook by events"功能上，只有部分事件能够正常保持设置。

问题表现

当用户在管理界面启用Webhook Base64选项并点击保存后，表面上看起来操作成功了。然而，一旦刷新页面，该选项就会自动恢复为禁用状态。这意味着系统实际上并未真正保存用户的配置选择，导致依赖此功能的自动化流程无法正常工作。

影响范围

这个问题影响了多个版本：

• 2.1.0版本首次报告该问题
• 2.2.0、2.2.2和2.2.3版本仍然存在相同问题
• 2.1.1-homolog版本被证实可以正常工作

临时解决方案

由于官方版本中该功能存在稳定性问题，社区用户探索出了几种替代方案：

1. 使用专用API端点获取Base64数据
   通过调用专门的API端点/chat/getBase64FromMediaMessage/{instância}可以获取媒体消息的Base64编码。这需要发送一个POST请求，包含以下内容：

   • Headers中设置API密钥
   • Body中包含消息ID和转换选项的JSON数据

2. 降级到2.1.1-homolog版本
   部分用户报告该特定版本功能正常，但这不是长期解决方案。

最佳实践建议

对于需要处理媒体消息Base64编码的场景，建议采用以下工作流程：

1. 配置常规webhook接收消息通知
2. 当收到包含媒体内容的消息时
3. 使用专用API端点主动获取Base64编码内容
4. 处理获取到的Base64数据

这种方法不仅更可靠，还能减少不必要的网络传输，因为只有在确实需要Base64数据时才发起请求。

技术实现示例

以下是获取媒体消息Base64编码的典型请求示例：

{
    "message": {
        "key": {
            "id": "消息ID"
        }
    },
    "convertToMp4": false
}

响应将包含媒体内容的Base64编码字符串，可直接用于后续处理。

总结

虽然Webhook Base64功能的自动发送在部分版本中存在稳定性问题，但通过使用专用API端点可以可靠地获取所需数据。建议开发者采用主动请求的方式替代依赖webhook自动发送Base64数据，这样不仅能解决当前问题，还能提高应用程序的健壮性和可控性。

对于依赖此功能的关键业务系统，建议密切关注EvolutionAPI的版本更新日志，待官方确认问题完全修复后再考虑切换回自动发送模式。