Webhook 通知
接入前请查看接口开放状态,并在目标环境确认账户权限。
| 操作 | 方法与路径 | 开放状态 |
|---|---|---|
| 创建通知端点 | POST /v1/webhook-endpoints | 开放待确认 |
| 列出通知端点 | GET /v1/webhook-endpoints | 开放待确认 |
| 更新通知端点 | PATCH /v1/webhook-endpoints/{id} | 开放待确认 |
| 删除通知端点 | DELETE /v1/webhook-endpoints/{id} | 开放待确认 |
本节提供接入约定,商户访问尚待确认。启用前请查看接口开放状态,完成目标环境的开通确认。
本文定义收款与退款共用的通知端点、事件格式、签名验证及投递规则。商户调用端点管理接口时,请求与认证、幂等、分页和错误响应沿用商户 API 通用约定。
Webhook Endpoints 通知端点
Webhook 端点是商户接收收款和退款事件通知的服务器地址。每个商户可以配置多个端点,各环境的端点独立管理。
同一事件投递给所有启用的端点,事件 id 相同。每个端点使用独立签名密钥,独立启停和重试;一个端点投递失败,不影响其他端点。
端点数量受商户配额限制。
Webhook Endpoint Object
Attributes
| 属性 | 类型 | 说明 |
|---|---|---|
id | string | 端点的唯一标识 |
url | string | 可公开访问的通知接收地址;正式环境必须使用 HTTPS,测试环境也允许 HTTP |
enabled | boolean | 是否启用通知投递,默认 true |
secret | string | 验证 Webhook 签名的密钥;仅创建及该操作的有效幂等重试返回,查询与更新不返回此属性 |
created_at | string | 创建时间 |
updated_at | string | 最后更新时间 |
secret 与 API Key 独立,应保存在商户服务端。
对象示例
以下为创建时返回的对象,包含签名密钥:
{
"id": "we_example",
"url": "https://merchant.example.com/webhooks/invisi",
"enabled": true,
"secret": "whsec_...",
"created_at": "2026-10-15T08:00:00Z",
"updated_at": "2026-10-15T08:00:00Z"
}
创建通知端点
POST /v1/webhook-endpoints
创建一个用于接收收款和退款事件通知的端点,并生成签名密钥。
Attributes
| 属性 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
Idempotency-Key | header | string | 是 | 本次操作的唯一键;重试沿用原值 |
url | body | string | 是 | 可公开访问的通知接收地址;正式环境必须使用 HTTPS,测试环境也允许 HTTP |
enabled | body | boolean | 否 | 是否启用通知投递,默认 true |
请求示例
POST /v1/webhook-endpoints
Authorization: Bearer inv_test_...
Content-Type: application/json
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
{
"url": "https://merchant.example.com/webhooks/invisi",
"enabled": true
}
返回示例
200 OK,返回完整的 Webhook Endpoint 对象,包含签名密钥。请保存 secret,后续查询与更新不返回此属性。
{
"id": "we_example",
"url": "https://merchant.example.com/webhooks/invisi",
"enabled": true,
"secret": "whsec_...",
"created_at": "2026-10-15T08:00:00Z",
"updated_at": "2026-10-15T08:00:00Z"
}
列出通知端点
GET /v1/webhook-endpoints
分页返回当前商户的通知端点,包含启用和停用的端点。
Attributes
| 属性 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
page_size | query | integer | 否 | 每页数量,默认 20,范围 1–100 |
page_token | query | string | 否 | 上一页返回的 next_page_token;第一页不传 |
请求示例
GET /v1/webhook-endpoints?page_size=20
Authorization: Bearer inv_test_...
返回示例
200 OK,data 为 Webhook Endpoint 对象数组,每个端点不包含 secret。next_page_token 为空字符串表示没有下一页。
{
"data": [
{
"id": "we_example",
"url": "https://merchant.example.com/webhooks/invisi",
"enabled": true,
"created_at": "2026-10-15T08:00:00Z",
"updated_at": "2026-10-15T08:00:00Z"
}
],
"next_page_token": ""
}
未配置端点时返回 {"data":[],"next_page_token":""}。
更新通知端点
PATCH /v1/webhook-endpoints/{id}
更新通知接收地址或启用状态。未传入的字段保持原值,签名密钥不变。
Attributes
| 属性 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
Idempotency-Key | header | string | 是 | 本次操作的唯一键;重试沿用原值 |
id | path | string | 是 | 端点的唯一标识 |
url | body | string | 否 | 新的通知接收地址,不能清空;地址要求与创建时相同 |
enabled | body | boolean | 否 | 是否启用通知投递;false 表示停用 |
请求示例
PATCH /v1/webhook-endpoints/we_example
Authorization: Bearer inv_test_...
Content-Type: application/json
Idempotency-Key: 65ded8e0-a034-49cb-8d7c-4b279a7382fd
{
"enabled": false
}
返回示例
200 OK,返回更新后的 Webhook Endpoint 对象,不包含 secret。
{
"id": "we_example",
"url": "https://merchant.example.com/webhooks/invisi",
"enabled": false,
"created_at": "2026-10-15T08:00:00Z",
"updated_at": "2026-10-15T08:10:00Z"
}
删除通知端点
DELETE /v1/webhook-endpoints/{id}
删除一个通知端点,停止向该端点投递新事件。删除后重新创建会生成新的端点 ID 和签名密钥。
Attributes
| 属性 | 位置 | 类型 | 必填 | 说明 |
|---|---|---|---|---|
Idempotency-Key | header | string | 是 | 本次操作的唯一键;重试沿用原值 |
id | path | string | 是 | 端点的唯一标识 |
无请求体。
请求示例
DELETE /v1/webhook-endpoints/we_example
Authorization: Bearer inv_test_...
Idempotency-Key: de68649e-3869-4d8c-b267-61e6e0732311
返回示例
200 OK,返回被删除端点的标识和删除结果。
{
"id": "we_example",
"deleted": true
}
同一删除操作的有效幂等重试仍返回首次成功响应。
错误码
以下错误适用于通知端点接口,响应结构和通用错误见错误响应。
error.code | HTTP 状态码 | 含义 | 适用接口 |
|---|---|---|---|
webhook_endpoint_not_found | 404 | 端点不存在或无权访问 | 更新、删除 |
webhook_endpoint_invalid_url | 400 | 通知接收地址不符合要求 | 创建、更新 |
webhook_endpoint_limit_exceeded | 409 | 已达到商户的端点数量配额 | 创建 |
Webhook Events 事件
平台通过 HTTP POST 向通知端点发送轻量事件通知(Thin Event),通知商户收款或退款变化。通知包含事件信息和关联资源的标识,商户根据 related_object.type 查询对应资源。
Event Object
Attributes
| 属性 | 类型 | 说明 |
|---|---|---|
id | string | 事件的唯一标识;用于识别重复通知 |
type | string | 事件类型,例如 checkout.succeeded 表示收款成功 |
related_object | object | 事件关联的资源 |
related_object.id | string | 资源 ID;查询对应资源时使用此值 |
related_object.type | string | 资源类型:收款为 checkout,退款为 refund |
created_at | string | 事件发生时间 |
重复投递同一事件时,事件 id 和内容保持不变。查询对应资源返回其当前状态,可能已发生后续变化。
对象示例
{
"id": "evt_example",
"type": "checkout.succeeded",
"related_object": {
"id": "checkout_example",
"type": "checkout"
},
"created_at": "2026-10-15T08:01:00Z"
}
关联资源
商户应先根据 related_object.type 区分资源,再使用 related_object.id 查询当前状态:
related_object.type | 查询接口 | 事件类型 |
|---|---|---|
checkout | 查询收款:GET /v1/checkouts/{id} | checkout.* |
refund | 查询退款:GET /v1/refunds/{id} | 退款事件 |
通知可能重复或乱序到达。按事件 id 去重,并查询对应资源确认当前状态,避免用较早的通知覆盖较新的状态。
接收事件
POST {通知端点的 url}
Attributes
| 位置 | 属性 | 类型 | 说明 |
|---|---|---|---|
| header | Content-Type | string | application/json |
| header | Invisi-Signature | string | 通知签名,见签名验证 |
| body | — | object | Event Object |
请求示例
POST /webhooks/invisi HTTP/1.1
Host: merchant.example.com
Content-Type: application/json
Invisi-Signature: t=<unix_seconds>,v1=<signature>
{
"id": "evt_example",
"type": "checkout.succeeded",
"related_object": {
"id": "checkout_example",
"type": "checkout"
},
"created_at": "2026-10-15T08:01:00Z"
}
响应
验证签名并可靠保存事件后,尽快返回 2xx,无需响应体。查询对应资源、履约等业务操作可异步完成。已接收的重复事件也应返回 2xx,避免重复执行业务操作。
HTTP/1.1 200 OK
Content-Length: 0
返回 2xx 仅表示事件已接收,后续业务处理失败由商户自行重试。未成功接收时,平台按投递与重试规则处理。
签名验证
使用该通知端点的 secret 验证每次请求,验证通过后再接收事件。签名位于请求头:
Invisi-Signature: t=<unix_seconds>,v1=<signature>
| 属性 | 说明 |
|---|---|
t | 本次投递的 Unix 时间戳,单位为秒 |
v1 | HMAC-SHA256 签名,使用小写十六进制编码 |
验签步骤:
-
读取原始请求体字节,保留空格、换行及字段顺序,不要解析后重新序列化。
-
以十进制时间戳、英文句点
.、原始请求体依次拼接,计算签名:signed_payload = t + "." + raw_bodyexpected = hex(HMAC-SHA256(secret, signed_payload)) -
使用恒定时间比较函数,将
expected与v1比较。secret使用创建端点时返回的完整字符串,不移除前缀或解码。 -
检查
t与当前时间的差值,建议仅接受前后 5 分钟内的请求,并保持服务器时钟同步。
签名缺失、格式错误、签名不匹配或时间超出允许范围时,拒绝请求且不处理事件。
每次重试使用新的投递时间戳并重新签名;事件 id 和请求体保持不变。时间校验不能代替事件去重。
投递与重试
每次投递的请求超时时间为 5 秒。平台按端点独立判断投递结果:
| 投递结果 | 处理方式 |
|---|---|
返回 2xx | 接收成功,停止该事件向该端点的自动重试 |
连接失败、响应超时或返回非 2xx | 接收失败,安排重试 |
返回 3xx | 不跟随重定向,按接收失败处理 |
投递失败后,平台自动重试,间隔逐步延长,最长持续至首次投递后的 3 天。接收成功、超过重试期限或端点停用、删除后,停止自动投递;已经发出的请求仍可能到达。
Webhook 投递失败不改变收款或退款状态。商户服务恢复后,应通过查询收款(GET /v1/checkouts/{id})、列出收款(GET /v1/checkouts)、查询退款或列出退款核对相关资源,补充处理遗漏的结果。