跳到主要内容

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​

属性类型说明
idstring端点的唯一标识
urlstring可公开访问的通知接收地址;正式环境必须使用 HTTPS,测试环境也允许 HTTP
enabledboolean是否启用通知投递,默认 true
secretstring验证 Webhook 签名的密钥;仅创建及该操作的有效幂等重试返回,查询与更新不返回此属性
created_atstring创建时间
updated_atstring最后更新时间

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-Keyheaderstring是本次操作的唯一键;重试沿用原值
urlbodystring是可公开访问的通知接收地址;正式环境必须使用 HTTPS,测试环境也允许 HTTP
enabledbodyboolean否是否启用通知投递,默认 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_sizequeryinteger否每页数量,默认 20,范围 1–100
page_tokenquerystring否上一页返回的 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-Keyheaderstring是本次操作的唯一键;重试沿用原值
idpathstring是端点的唯一标识
urlbodystring否新的通知接收地址,不能清空;地址要求与创建时相同
enabledbodyboolean否是否启用通知投递;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-Keyheaderstring是本次操作的唯一键;重试沿用原值
idpathstring是端点的唯一标识

无请求体。

请求示例​

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.codeHTTP 状态码含义适用接口
webhook_endpoint_not_found404端点不存在或无权访问更新、删除
webhook_endpoint_invalid_url400通知接收地址不符合要求创建、更新
webhook_endpoint_limit_exceeded409已达到商户的端点数量配额创建

Webhook Events 事件​

平台通过 HTTP POST 向通知端点发送轻量事件通知(Thin Event),通知商户收款或退款变化。通知包含事件信息和关联资源的标识,商户根据 related_object.type 查询对应资源。

Event Object​

Attributes​

属性类型说明
idstring事件的唯一标识;用于识别重复通知
typestring事件类型,例如 checkout.succeeded 表示收款成功
related_objectobject事件关联的资源
related_object.idstring资源 ID;查询对应资源时使用此值
related_object.typestring资源类型:收款为 checkout,退款为 refund
created_atstring事件发生时间

重复投递同一事件时,事件 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​

位置属性类型说明
headerContent-Typestringapplication/json
headerInvisi-Signaturestring通知签名,见签名验证
body—objectEvent 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 时间戳,单位为秒
v1HMAC-SHA256 签名,使用小写十六进制编码

验签步骤:

  1. 读取原始请求体字节,保留空格、换行及字段顺序,不要解析后重新序列化。

  2. 以十进制时间戳、英文句点 .、原始请求体依次拼接,计算签名:

    signed_payload = t + "." + raw_body
    expected = hex(HMAC-SHA256(secret, signed_payload))
  3. 使用恒定时间比较函数,将 expected 与 v1 比较。secret 使用创建端点时返回的完整字符串,不移除前缀或解码。

  4. 检查 t 与当前时间的差值,建议仅接受前后 5 分钟内的请求,并保持服务器时钟同步。

签名缺失、格式错误、签名不匹配或时间超出允许范围时,拒绝请求且不处理事件。

每次重试使用新的投递时间戳并重新签名;事件 id 和请求体保持不变。时间校验不能代替事件去重。

投递与重试​

每次投递的请求超时时间为 5 秒。平台按端点独立判断投递结果:

投递结果处理方式
返回 2xx接收成功,停止该事件向该端点的自动重试
连接失败、响应超时或返回非 2xx接收失败,安排重试
返回 3xx不跟随重定向,按接收失败处理

投递失败后,平台自动重试,间隔逐步延长,最长持续至首次投递后的 3 天。接收成功、超过重试期限或端点停用、删除后,停止自动投递;已经发出的请求仍可能到达。

Webhook 投递失败不改变收款或退款状态。商户服务恢复后,应通过查询收款(GET /v1/checkouts/{id})、列出收款(GET /v1/checkouts)、查询退款或列出退款核对相关资源,补充处理遗漏的结果。