RecraftWebhook配置详解与教程

API开发者若想在Recraft平台实现图像生成完成、配额变更等关键事件的实时响应，必须精准完成HTTPS回调服务部署、Challenge验证、X-Hub-Signature-256签名校验或AES-GCM加密解密、以及按type字段动态解析generation.completed等结构化事件数据——本教程手把手拆解五大核心环节，助你安全、稳定、低延迟地接入Recraft Webhook，真正将平台能力无缝融入自身业务流。

如果您是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状态重复投递。

今天关于《RecraftWebhook配置详解与教程》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！