Minimax API 如何配置 Webhook 接收任务结果？

来到golang学习网的大家，相信都是编程学习爱好者，希望在这里学习科技周边相关编程知识。下面本篇文章就来带大家聊聊《Minimax API 如何配置 Webhook 接收任务结果？》，介绍一下，希望对大家的知识积累有所帮助，助力实战开发！

需配置HTTPS回调端点、在请求中传入webhook_url、验证X-Minimax-Signature签名、可选设全局Webhook、通过控制台日志调试；所有步骤须确保3秒内返回200且使用有效TLS证书。

如果您希望 Minimax API 在任务完成后通过 Webhook 通知您的服务，则需在调用任务接口时指定有效的回调地址，并确保该地址能正确响应 Minimax 发起的 HTTP POST 请求。以下是配置 Webhook 接收任务结果的具体步骤：

一、准备可公开访问的 HTTPS 回调端点

Minimax 要求 Webhook 地址必须为 HTTPS 协议，且服务器需具备有效 TLS 证书，不能使用自签名证书或 localhost 地址。该端点需能接收 application/json 格式的 POST 请求，并在 3 秒内返回 HTTP 200 状态码，否则 Minimax 将视为回调失败并可能重试。

1、部署一个支持 HTTPS 的 Web 服务，例如使用 Nginx + Let’s Encrypt 或云函数（如阿里云函数计算、Vercel、Cloudflare Workers）暴露公网端点。

2、确保该端点路径（如 https://yourdomain.com/minimax/webhook）已配置 CORS（非必需但建议），且不强制校验请求来源。

3、在服务代码中添加对 POST /minimax/webhook 路径的处理逻辑，解析原始 JSON 体，提取 task_id、status、result 等字段。

二、在任务请求中传入 webhook_url 参数

调用 Minimax 的异步任务接口（例如 text_to_speech、chat_completion 等带 async=true 的版本）时，需在请求体中显式提供 webhook_url 字段，其值为上一步准备好的 HTTPS 地址。Minimax 将在任务状态变更（尤其是 status 变为 success 或 failed）时向该地址推送结果。

1、构造 JSON 请求体，包含必需参数及 webhook_url 字段，例如：{"model": "abab6.5-chat", "messages": [...], "async": true, "webhook_url": "https://yourdomain.com/minimax/webhook"}。

2、使用 curl 或 SDK 发送 POST 请求至 Minimax 对应的异步接口 URL（如 https://api.minimax.chat/v1/text/chatcompletion_pro）。

3、记录返回的 task_id，用于后续比对 Webhook 中收到的 task_id，防止伪造请求或重复处理。

三、验证并响应 Minimax 的 Webhook 请求

Minimax 向您端点发送的请求携带 X-Minimax-Signature 头，用于签名验证。您需使用平台提供的 secret（在 Minimax 控制台 Webhook 设置页获取）对原始请求体进行 HMAC-SHA256 签名比对，确保请求真实来自 Minimax。

1、从请求头中提取 X-Minimax-Signature 值，格式为 t={timestamp},v1={signature}。

2、将时间戳与请求体原文拼接（如 timestamp + "." + raw_body），用您的 webhook_secret 进行 HMAC-SHA256 计算，并将结果转为十六进制小写字符串。

3、比对计算出的 signature 与 header 中 v1 后的值是否一致；一致则继续处理，否则返回 HTTP 401 并终止。

四、配置 Minimax 控制台全局 Webhook（可选替代方式）

若多个任务共用同一回调逻辑，可在 Minimax 开发者控制台中设置全局默认 Webhook 地址。该配置将自动应用于所有未显式传入 webhook_url 的异步任务请求，减少每次调用的手动传参负担。

1、登录 Minimax 控制台，进入「API 密钥与 Webhook」页面。

2、在「Webhook 设置」区域填写 https://yourdomain.com/minimax/webhook，并保存 secret（该 secret 仅显示一次，请立即备份）。

3、启用「启用全局 Webhook」开关；此后发起 async=true 请求时，即使不带 webhook_url 字段，也将默认触发此地址。

五、调试 Webhook 接收行为

Minimax 提供 Webhook 日志查询功能，可用于确认请求是否成功发出、目标服务器是否响应 200、签名验证是否通过。当接收异常时，日志中会明确标注错误类型（如 connection timeout、invalid signature、non-2xx response）。

1、在控制台「Webhook 日志」页筛选目标 task_id 或时间范围，查看最近 7 天内的全部回调记录。

2、对失败条目点击「重试」按钮，触发 Minimax 再次推送相同 payload（仅限 3 次重试机会）。

3、在本地使用 ngrok 或 localtunnel 创建临时 HTTPS 隧道，将 https://xxx.ngrok.io/minimax/webhook 作为测试地址接入控制台，快速验证端点逻辑。

到这里，我们也就讲完了《Minimax API 如何配置 Webhook 接收任务结果？》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！