设置回调配置
设置当前租户的公网 HTTPS:443 回调地址与开关。配置变更不会改写已有轮次的固定回调地址。
POST /open/v1/settings/webhook
请求头
| 字段 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| X-App-Id | string | 是 | 平台appID，规范正int64，只传一次。 | 123456789012345001 |
| X-Timestamp | string | 是 | 当前秒级时间戳，服务器时间前后300秒内。 | 1893456000 |
| X-Sign | string | 是 | 本次HMAC-SHA256签名，64位小写十六进制；按签名规则生成。 | 按本次请求计算 |
| Authorization | string | 是 | 当前有效accessToken，格式为 Bearer 后加令牌。 | Bearer <ACCESS_TOKEN> |
| Content-Type | string | 是 | 单个UTF-8 JSON对象。 | application/json |
认证只使用上表请求头；不要发送 Idempotency-Key。示例凭据、ID和地址是演示值，签名必须按实际参数和当前时间重新计算。
请求参数
无路径参数，不接受任何Query（包括仅有问号的URL）。以下字段全部放JSON，额外字段返回400。
| 字段 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| url | string | 是 | 公网 HTTPS 回调地址，只允许默认端口或 443；不含用户凭据或片段。关闭时可为空字符串。 | "https://merchant.example.com/guiji/webhook" |
| enabled | boolean | 是 | 是否开启新通知轮次的正常投递；开启时必须有合法非空 URL。 | true |
| request_id | string | 是 | 持久化幂等键，JSON 字符串，UTF-8 字节长度16–128，推荐ASCII UUID。创建钱包/归集、修改业务设置、通知重推必填。同租户同操作同键同参数返回原成功结果；同键异参409。只放JSON body，参与签名，不接受Idempotency-Key头。 | "123e4567-e89b-42d3-a456-426614174000" |
json
{
"url": "https://merchant.example.com/guiji/webhook",
"enabled": true,
"request_id": "webhook-config-20300101-0001"
}业务规则
必须提交 url 和 enabled。URL非空时，无论是否开启都校验格式、DNS与公网IP；仅允许 HTTPS 和443端口，不允许用户凭据、URL片段、内网/本机地址或重定向。开启时URL不能为空。
设置成功不表示已经发生到账或投递；平台不会因保存配置创建测试事件。新事件和重新推送的新轮次读取当前配置，已有轮次继续使用原来的地址。关闭或未配置时，新轮次明确记录异常，不无限等待。
只有通知异常后，才可调用重新推送开启新一轮。新轮次仍使用原固定事件ID，接收方必须持续按事件ID去重。
幂等
JSON request_id 必填，16–128个UTF-8字节，推荐ASCII UUID；与业务参数一起参与签名。同租户同操作同键同参数返回原结果，同键不同参数返回409。超时重试保持原编号，读取最新配置请调用对应GET接口。
成功响应
HTTP 200，外层code=0、message为空字符串。
json
{
"code": 0,
"message": "",
"data": {
"url": "https://merchant.example.com/guiji/webhook",
"enabled": true
}
}| 字段 | 类型 | 必填 | 说明 | 示例值 |
|---|---|---|---|---|
| code | integer | 是 | 业务成功。 | 0 |
| message | string | 是 | 成功时为空字符串。 | "" |
| data | object | 是 | 本次保存的回调配置；幂等重试返回原保存结果。 | "见 JSON 示例" |
| data.url | string | 是 | 公网 HTTPS 回调地址，只允许默认端口或 443；不含用户凭据或片段。关闭时可为空字符串。 | "https://merchant.example.com/guiji/webhook" |
| data.enabled | boolean | 是 | 是否开启新通知轮次的正常投递；开启时必须有合法非空 URL。 | true |
失败响应
错误JSON没有data；HTTP状态与code一致。
| HTTP | 情况 |
|---|---|
| 400 | 参数缺失、类型/格式无效或存在不支持的字段 |
| 401 | accessToken、签名或签名时间窗口无效 |
| 403 | 租户停用、删除或过期 |
| 409 | request_id已被同操作不同业务参数使用，或业务状态冲突 |
| 413 / 429 | 请求体过大 / 请求频率超限 |
| 500 / 503 / 504 | 内部依赖错误 / 资源或配置不可用 / 请求超时 |
json
{
"code": 401,
"message": "authentication required or expired",
"error_code": "TOKEN_INVALID_OR_EXPIRED",
"trace_id": "0123456789abcdef0123456789abcdef"
}通用错误说明Retry-After及重试处理；写请求不要因超时生成新的request_id。
业务错误示例
HTTP 400：开启回调但没有填写地址。
json
{
"code": 400,
"message": "webhook URL required when enabled",
"error_code": "INVALID_ARGUMENT",
"trace_id": "0123456789abcdef0123456789abcdef"
}HTTP 409：尚未开通租户主账号及对应配置。
json
{
"code": 409,
"message": "tenant owner must be provisioned first",
"error_code": "BUSINESS_CONFLICT",
"trace_id": "0123456789abcdef0123456789abcdef"
}完整字段与状态
查看全部响应字段、嵌套对象及枚举 · 业务状态与处理 · 错误码排查。