Recraft Webhook回调配置全解析

本文深入解析了在Recraft平台中配置Webhook回调的完整流程，涵盖从公网HTTPS服务部署、Challenge验证响应、X-Hub-Signature-256签名校验或encrypt字段解密，到精准解析generation.completed等核心事件数据的全链路实践要点，为API开发者提供了一套安全、可靠、可落地的实时事件集成方案，助你轻松打通Recraft与自有系统间的自动化通知闭环。

如果您是API开发者，希望在Recraft平台中启用Webhook回调功能以接收实时事件通知，则需完成回调地址注册、签名验证与事件响应等关键配置。以下是具体操作步骤：

一、准备接收端服务

Recraft Webhook要求回调URL为公网可访问、支持HTTPS、能稳定响应POST请求且返回HTTP 200状态码。接收端必须具备解析JSON数据、处理zlib压缩（如启用）、校验签名或解密加密字段的能力。

1、部署一个支持HTTP POST的Web服务，监听指定端口并暴露至公网。

2、确保服务能接收application/json格式请求体，并在收到请求后1秒内返回HTTP 200响应。

3、若Recraft启用了消息压缩，服务需集成zlib解压逻辑；若启用加密，须按Recraft文档实现对应解密流程。

二、配置Recraft平台Webhook地址

在Recraft开发者控制台中注册回调URL，该地址将作为所有事件推送的唯一入口。平台仅允许为每个应用配置一个有效回调地址，且不可与其他通信模式（如WebSocket）共存。

1、登录Recraft开发者后台，进入目标应用的「设置」→「连接方式」页面。

2、选择「Webhook」作为消息接收模式。

3、在Callback URL字段中填入您已部署的服务地址，例如：https://yourdomain.com/recraft-webhook。

4、保存配置后，平台将立即发起Challenge验证请求。

三、响应Challenge验证请求

Recraft在首次配置或重试时，会向您填写的Callback URL发送一条包含challenge值的验证请求，用于确认服务可达性与响应能力。该请求为application/json格式，且无论是否启用加密，均需原样返回challenge字段。

1、监听POST请求，解析请求体中的JSON内容。

2、提取challenge字段值，例如"challenge": "a1b2c3d4e5f6"。

3、构造响应体：{"challenge":"a1b2c3d4e5f6"}，并以HTTP 200状态返回。

4、响应必须在1秒内完成，超时将导致配置失败。

四、处理签名与加密校验

Recraft Webhook推送中可能携带签名头（如X-Hub-Signature-256）或加密字段（如encrypt），用于保障消息来源可信与内容机密。接收端需主动校验签名或解密payload，否则无法安全使用事件数据。

1、检查HTTP请求头中是否存在X-Hub-Signature-256字段。

2、使用您在Recraft平台配置的Secret密钥，对原始请求体进行HMAC-SHA256计算，比对签名值是否一致。

3、若请求体含encrypt字段，需调用Recraft指定的AES-GCM解密算法，使用Secret作为密钥还原原始JSON。

4、校验失败时应拒绝处理该请求，并记录日志。

五、解析并响应标准事件

通过Challenge验证后，Recraft将在触发事件（如图像生成完成、模型调用异常、资源配额变更）时，向您的回调URL推送结构化事件数据。每类事件的data字段结构不同，需按类型分别解析。

1、读取请求体JSON，提取type字段识别事件类型，例如"type": "generation.completed"。

2、根据type值匹配对应schema，提取关键字段如data.jobId、data.status、data.resultUrl等。

3、执行业务逻辑，如下载生成图、更新数据库状态、触发下游通知。

4、始终返回HTTP 200空响应，避免Recraft因超时或非200状态重复投递。

好了，本文到此结束，带大家了解了《Recraft Webhook回调配置全解析》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多科技周边知识！