● 回调管理 · /v1

回调管理

注册端点、轮换密钥、查投递记录、手动重发。你的系统挂过一段时间之后,靠这组接口自助补齐。

列出回调端点

GET /v1/webhooks/endpoints

响应 200

uid string
url string 必须是 https。我们不会往 http 投递
events string[] 订阅的事件类型,空数组表示全订阅
status active | paused | disabled paused 是连续投递失败后自动停投,修好后调 resend 补
description string
secret_preview string 密钥只在创建和轮换时完整返回一次,之后只给尾段
created_at string<date-time>
请求
curl -X GET https://api.baton.example/v1/webhooks/endpoints \
  -H "Authorization: Bearer sk_live_xxx"
响应 · 200
[
  {
    "uid": "WE20261116000001",
    "url": "https://hooks.example.com/baton",
    "events": [
      "payment.status_changed",
      "refund.status_changed"
    ],
    "status": "active",
    "secret_preview": "...7f3a",
    "created_at": "2026-10-02T03:11:00Z"
  }
]

注册回调端点

POST /v1/webhooks/endpoints

必须是公网可达的 https,内网和保留地址会被拒。签名密钥只在这一次响应里完整返回, 之后接口只给尾段——存不下来就只能轮换。

请求头

Idempotency-Key必填 string 商户生成的唯一串(建议 UUID/ULID)。24 小时内重放同一 key 返回首次结果,不会产生第二笔。

请求体

url必填 string
events string[] 留空表示全订阅。建议显式列出,将来加了新事件不会突然打到你的老代码上
description string

错误

400参数不合法
请求
curl -X POST https://api.baton.example/v1/webhooks/endpoints \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://hooks.example.com/baton",
  "events": [
    "payment.status_changed",
    "refund.status_changed"
  ],
  "description": "prod order service"
}'
响应 · 201
{
  "uid": "WE20261116000001",
  "url": "https://hooks.example.com/baton",
  "events": [
    "payment.status_changed"
  ],
  "status": "active",
  "secret": "whsec_live_9f3a2c7e...",
  "created_at": "2026-11-16T09:45:00Z"
}

轮换签名密钥

POST /v1/webhooks/endpoints/{uid}/rotate-secret

新旧密钥在轮换期内同时有效 24 小时,回调头里会出现两个 v1=, 你任一验过即可。等你的服务全部换完,旧密钥自动失效——不需要停机。

路径参数

uid必填 string

请求头

Idempotency-Key必填 string 商户生成的唯一串(建议 UUID/ULID)。24 小时内重放同一 key 返回首次结果,不会产生第二笔。

响应 200

secret string
old_secret_expires_at string<date-time>
请求
curl -X POST https://api.baton.example/v1/webhooks/endpoints/{uid}/rotate-secret \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."
响应 · 200
{
  "secret": "whsec_live_2b8e41d0...",
  "old_secret_expires_at": "2026-11-17T09:45:00Z"
}

投递记录

GET /v1/webhooks/deliveries

排障先看 response_excerpt——那是你自己返回的响应体前 512 字节。 九成「我没收到回调」的实际情况是你返回了 500 或者超过 5 秒。

Query 参数

event_id string
endpoint_uid string
status pending | delivered | failed | abandoned
created_from string<date-time>
created_to string<date-time>
cursor string 上一页返回的 page.next_cursor
limit integer

响应 200

data object[]
└uid string
└event_id string 事件 ID,你用这个做幂等去重
└event_type string
└endpoint_uid string
└status pending | delivered | failed | abandoned
└http_status integer
└response_excerpt string 你的响应体前 512 字节,脱敏后存。排障时先看这个
└attempt_no integer
└next_retry_at string<date-time>
└created_at string<date-time>
page object
└next_cursor string
└has_more boolean
请求
curl -X GET https://api.baton.example/v1/webhooks/deliveries \
  -H "Authorization: Bearer sk_live_xxx"

重发回调

POST /v1/webhooks/deliveries/{uid}/resend

你的服务挂了一段时间之后,用这个自助补齐,不用找我们。 重发的事件 id 不变,所以你那边的幂等去重必须先做好,否则补一次重复处理一次。

批量补:先用投递记录按时间段 + status=failed 查出来,再逐条重发。

路径参数

uid必填 string

请求头

Idempotency-Key必填 string 商户生成的唯一串(建议 UUID/ULID)。24 小时内重放同一 key 返回首次结果,不会产生第二笔。

响应 202

uid string
event_id string 事件 ID,你用这个做幂等去重
event_type string
endpoint_uid string
status pending | delivered | failed | abandoned
http_status integer
response_excerpt string 你的响应体前 512 字节,脱敏后存。排障时先看这个
attempt_no integer
next_retry_at string<date-time>
created_at string<date-time>

错误

404对象不存在,或属于另一个环境 / 另一个商户
请求
curl -X POST https://api.baton.example/v1/webhooks/deliveries/{uid}/resend \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."

删除回调端点

POST /v1/webhooks/endpoints/{uid}/delete

删除后在途的投递仍会尝试完当前这一轮,不会凭空消失。

路径参数

uid必填 string

响应 200

uid string
deleted boolean

错误

404对象不存在,或属于另一个环境 / 另一个商户
请求
curl -X POST https://api.baton.example/v1/webhooks/endpoints/{uid}/delete \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."