查询当前 Webhook 通知配置

GET/v1/webhook-config

接入方服务端 → 支付服务

服务端签名认证

每次请求按方法、路径、时间戳、原始 query 与原始正文计算 HMAC。先完成身份验证和环境配置。

调用说明

当前服务把 environment 固定为 test，不通过此接口切换。由平台管理员在「接入方管理 → Webhook 通知配置」保存，接入方只能读取自己的配置。

调用时机

接入时核对平台实际投递的通知地址，或排查通知暂停、缺少签名配置时调用。响应中的 url 就是后续投递目标。接收进程前面若有反向代理，它可能和进程自己的监听地址不同。

调用步骤

使用当前环境的 API 凭据发送签名 GET 请求，不传 query 或 body。
读取 url、enabled、signingConfigured 和 availability。version 是十进制字符串，不能转换为浮点数。
availability 为 ready 仅表示配置满足发送前提，不表示目标连通或通知已送达；投递仍会执行目标网络策略和签名应答校验。

结果处理

修改配置后，后续及仍可重试的通知使用新目标，保留原 eventId 和正文；已送达或已达重试上限的通知不因修改而重放。在途请求可以完成。环境由服务端固定，不通过此接口切换。

失败与重试

401 先检查签名；422 检查是否误带 query 或 body；503 表示配置未知，先检查平台配置表、运行账号权限和服务日志，不能回退旧地址或宣称已连通。配置读取失败不应阻止原账本查询和刷新。

请求头

请求头	说明
`X-Access-Key`必填	平台发放的 API Access Key，用于识别你的业务后端。每个请求发送一次；只在服务端保存。
`X-Timestamp`必填	本次请求的 Unix 秒，使用十进制字符串。与服务端时间相差不得超过 300 秒；每个请求发送一次，重试重新生成。
`X-Signature`必填	本次 API 请求的 HMAC-SHA256 签名，64 个小写十六进制字符。使用 API 密钥签 METHOD\|PATH\|TIMESTAMP\|QUERY\|BODY，保留实际路径、query 和 body 字节；每个请求发送一次。

GET 请求的 body 必须为空；只发送本页列出的路径和 query 参数。

响应字段

200 成功响应

当前配置及发送前提状态，不包含签名凭据或管理员身份。

application/json

固定返回值
`environment`	`test`

`availability`4 个取值
含义与取值
`ready`
`paused`
`unconfigured`
`missing_credentials`

accessIdstring必返

当前认证接入方标识。

environmentstring必返

服务端固定的当前环境，只读。

取值：test

urlstring必返

实际投递目标；空字符串表示尚未配置。仅测试回环可使用 HTTP，其余地址须为 HTTPS；不得包含凭据、query 或 fragment。

最多字符数：2048

enabledboolean必返

是否启用后续通知投递。暂停期间保留待投递记录，不消耗 HTTP 重试次数。

versionstring必返

配置版本，以规范十进制字符串传递，范围 1–18446744073709551615，最多 20 位；保存原字符串，精确比较版本。

格式规则：^[1-9][0-9]{0,19}$；最少字符数：1；最多字符数：20；字符串表示的数值下限：1；字符串表示的数值上限：18446744073709551615；pattern 只校验规范十进制写法与位数；自定义整数上下界不是标准 JSON Schema 校验，须用大整数精确比较，不使用浮点。

updatedAtstring必返

最近一次配置修改时间。

格式：date-time

signingConfiguredboolean必返

后端私有签名凭据是否已配置；不返回凭据原文。

availabilitystring必返

ready=发送前提已配置，paused=暂停，unconfigured=地址为空，missing_credentials=缺少签名凭据。此状态不证明目标连通。

取值：ready、paused、unconfigured、missing_credentials

不接受未定义字段。

HTTP 状态码

状态码	含义与处理
`200`	当前配置及发送前提状态，不包含签名凭据或管理员身份。
`401`	请求未通过验签。先核对 Access Key、Unix 秒、路径/query 和原始 body，再重新签名请求。取址和充值接口在正文读取失败或超过 1 MiB 时也返回此状态。提现提交、取消、玩家提现列表和通知配置的超限正文返回 422，不是 401。
`422`	查询格式不正确。检查路径参数，仅保留接口允许的 query，并保证 GET body 为空；修正后可重新查询。
`503`	当前读不到通知配置。先检查平台配置、运行账号权限和服务日志。不能回退到旧地址，也不能把本次失败说成目标已连通。配置读取失败不改变原账本，可以继续查询充值和提现。

失败时先核对 HTTP 状态、原始签名内容和环境配置，见错误处理。

接口规范与环境配置

规范包含当前主动接口、每日提现上限查询和一个通知接收操作。高级 24 小时充值对账接口仅收起展示，旧直链和下载规范保留；每日上限查询读取与后台相同的当前规则；仍须核对本环境服务版本与数据库依赖。字段、必填项、枚举和示例见各接口；机器可读版本为 OpenAPI 3.0 规范。

操作	方法与路径	用途
createDepositAddress	`POST /v1/addresses`	获取玩家充值地址
listPlayerDeposits	`GET /v1/players/{playerId}/deposits?chainId=...`	充值页查进度
queryDeposit	`GET /v1/deposits/{txRef}`	复核单笔充值
submitWithdrawal	`POST /v1/withdrawals`	提交提现申请
listPlayerWithdrawals	`GET /v1/players/{playerId}/withdrawals?chainId=...&page=1&pageSize=20`	分页补查玩家该链已受理提现
queryWithdrawal	`GET /v1/withdrawals/{withdrawOrderId}`	查询提现最新状态
cancelWithdrawal	`POST /v1/withdrawals/{withdrawOrderId}/cancel`	取消尚未进入链上处理的提现，成功后为 `refunded`
queryWithdrawalQuota	`GET /v1/withdrawal-quota?playerId=...&chainId=...`	读取与后台相同的当前每日上限和当日申请额；quota:null 表示不限额
getWebhookConfig	`GET /v1/webhook-config`	只读核对通知 URL、启用状态、凭据是否配置、可用性及配置版本；不代表已送达
receiveTerminalNotice	`POST {notifyUrl}`	你的端点接收交易通知

导入 API 工具后，将 servers[0].variables.baseUrl.default 设为平台发放的 API 接入地址；每次调用都重新签名。通知操作独立使用你的完整通知 URL：notifyOrigin 只填协议、主机和端口，操作路径填写接收端的实际路径。默认 /notify 只是示意，不要在已有路径后再次追加，也不能把它当作业务 API 路径。预期工具最终请求的地址与对应环境配置一致；不一致时先检查主机、路径及前缀的拼接。