POST /v1/webhooks/endpoints
必须是公网可达的 https,内网和保留地址会被拒。签名密钥只在这一次响应里完整返回,
之后接口只给尾段——存不下来就只能轮换。
请求头
Idempotency-Key必填 | string | 商户生成的唯一串(建议 UUID/ULID)。24 小时内重放同一 key 返回首次结果,不会产生第二笔。 |
请求体
url必填 | string | |
events | string[] | 留空表示全订阅。建议显式列出,将来加了新事件不会突然打到你的老代码上 |
description | string | |
错误
请求
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=,
你任一验过即可。等你的服务全部换完,旧密钥自动失效——不需要停机。
路径参数
请求头
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"
} POST /v1/webhooks/deliveries/{uid}/resend
你的服务挂了一段时间之后,用这个自助补齐,不用找我们。
重发的事件 id 不变,所以你那边的幂等去重必须先做好,否则补一次重复处理一次。
批量补:先用投递记录按时间段 + status=failed 查出来,再逐条重发。
路径参数
请求头
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
删除后在途的投递仍会尝试完当前这一轮,不会凭空消失。
路径参数
响应 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=..."