开发者文档 · 协议版本 V1 · 更新于 2026-10-16

KartClub Webhook

接收完赛成绩、收车提醒与超圈提醒。本文包含接入所需的请求格式、签名规则、字段定义和代码示例。

使用 Codex 或 Claude Code 接入

Agent 版包含完整协议和实现检查项。复制全文后，直接粘贴到 Codex、Claude Code 或其他编码 Agent 中。

# KartClub Webhook V1 - Agent implementation specification

Use this document as the complete implementation specification for a KartClub Webhook receiver. Implement the receiver in the customer's existing stack and follow every MUST requirement below. Do not infer fields that are not documented.

Public human-readable documentation: <https://kart.club/docs/webhooks>

## 1. Required receiver behavior

1. Expose a publicly reachable HTTPS POST endpoint with a valid public-CA certificate.
2. Read the raw request body bytes before JSON parsing.
3. Validate `X-KC-Timestamp` and `X-KC-Signature` before parsing or storing the payload.
4. Reject timestamps more than 300 seconds before or after the receiver's current time.
5. Use a constant-time comparison for the signature.
6. Parse JSON only after signature validation succeeds.
7. Treat `e` as the event idempotency key and enforce uniqueness in the database.
8. Treat `r` only as the identifier used to correlate events for the same race result.
9. Keep `x = 1` simulated events out of production business tables.
10. Return HTTP 2xx only after the event is durably accepted. `204 No Content` is recommended.
11. Return within 2 seconds where possible. KartClub allows up to 2 seconds to connect, up to 5 seconds for any response read, and up to 8 seconds for the entire request.
12. Ignore unknown additional fields, but reject unsupported values of `v`.

## 2. Endpoint requirements

- Scheme: `https://`
- Method: `POST`
- Certificate: valid chain issued by a public CA
- Address: public internet only; no private, loopback, link-local, or reserved destination
- Redirects: not followed by KartClub
- Recommended response body: empty
- One URL per venue: each endpoint URL has its own signing secret. When one receiver serves several venues, give each venue a distinct URL (for example, a distinct path segment) and select the signing secret from the URL that received the request.

## 3. Events

| Chinese name | Event name | `t` | Trigger |
|---|---|---|---|
| 连通性测试 | `webhook.test` | `wt` | Manual connectivity test |
| 完赛成绩 | `race.result_finalized` | `rf` | A valid result finishes settlement |
| 收车提醒 | `rolling.return_due_soon` | `rr` | One lap or 60 seconds remains |
| 超圈提醒 | `rolling.purchase_limit_reached` | `rl` | Purchased lap/time limit is reached or exceeded |

The same result may produce `rr`, `rl`, and `rf` events. Those events share `r` but have different `e` values.

Events are not guaranteed to arrive in occurrence order. For example, `rf` can arrive before an `rl` that is waiting for a retry. `o` does not change across retries and reflects when the event actually occurred.

## 4. HTTP request

```http
POST /kartclub/webhooks HTTP/1.1
Host: hooks.example.com
Content-Type: application/json; charset=utf-8
User-Agent: KartClub-Webhook/1.0
X-KC-Timestamp: 1787196896
X-KC-Signature: v1.ESQi38l2tpSgp6ToapkbI9nEpmioQL8z_aIzMeo-NnY

{"t":"wt","v":1,"e":"abcdefghijklmnop","o":"2026-08-20T12:34:56+08:00","r":"ponmlkjihgfedcba"}
```

| Header | Value |
|---|---|
| `Content-Type` | `application/json; charset=utf-8` |
| `User-Agent` | `KartClub-Webhook/1.0` |
| `X-KC-Timestamp` | Unix timestamp in seconds |
| `X-KC-Signature` | `v1.` plus unpadded Base64URL HMAC-SHA256 digest |

## 5. Signature validation

The signing secret is an unpadded Base64URL string. Decode it before using it as the HMAC key.

```text
message   = ASCII(X-KC-Timestamp) + "." + raw HTTP body bytes
digest    = HMAC-SHA256(decoded_signing_secret, message)
expected  = "v1." + Base64URL_without_padding(digest)
valid     = timestamp_is_integer
            AND abs(receiver_unix_time - timestamp) <= 300
            AND constant_time_equal(expected, X-KC-Signature)
```

MUST NOT parse and reserialize JSON before validation. Whitespace, key order, and escaping are part of the signed raw body.

### Fixed test vector

```text
secret    = MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY
timestamp = 1787196896
body      = {"t":"wt","v":1,"e":"abcdefghijklmnop","o":"2026-08-20T12:34:56+08:00","r":"ponmlkjihgfedcba"}
signature = v1.ESQi38l2tpSgp6ToapkbI9nEpmioQL8z_aIzMeo-NnY
```

An automated test MUST verify this exact vector. Add negative tests for a modified body, modified timestamp, modified signature, malformed timestamp, and timestamp outside the 300-second window.

## 6. Common payload fields

All payloads are compact UTF-8 JSON.

| Key | Meaning | Type | Description |
|---|---|---|---|
| `t` | event type | string | `wt`, `rf`, `rr`, or `rl` |
| `v` | event version | integer | `1` for V1 |
| `e` | event ID | string | 16 characters; idempotency key |
| `o` | occurred at | string | Time this event was triggered; ISO 8601 with timezone |
| `r` | result ID | string | 16 characters; cross-event result correlation |
| `x` | test marker | integer | optional; `1` means simulated business data |

The exact meaning of `o` depends on `t`: it is the admin test send time for `wt`, result settlement completion time for `rf`, and threshold time for `rr` or `rl`.

## 7. `race.result_finalized` (`rf`)

```json
{
  "t": "rf",
  "v": 1,
  "e": "FzxY8W2jPa3kLm9Q",
  "o": "2026-08-20T12:34:56+08:00",
  "r": "nKaLjg6RqgT0bcA0",
  "s": "2026-08-20T12:24:20+08:00",
  "f": "2026-08-20T12:34:20+08:00",
  "ve": { "i": "DBLwV6V8oFvA1ADo", "n": "示例车场" },
  "rc": { "i": "f07ELvqKvP4QwFjJ", "n": "成人竞速" },
  "di": "qgP7YieaW9oUW1xG",
  "dn": "车手昵称",
  "a": "https://a.kart.yun/BGqSn5AAAQIDBAUGBxnlf_fDiS0GmcK8Mg9a1duRELjZJfZ-YEgIWE7uIoulSQ",
  "b": 52341
}
```

| Key | Meaning | Type | Description |
|---|---|---|---|
| `s` | started at | string | ISO 8601 race record start time with timezone; dispatch time in rolling mode |
| `f` | finished at | string | ISO 8601 result completion time with timezone |
| `ve.i` | venue ID | string | unique venue ID |
| `ve.n` | venue name | string | venue name |
| `rc.i` | race class ID | string | unique class/group ID |
| `rc.n` | race class name | string | class/group name |
| `di` | driver ID | string/null | unique driver ID; `null` for guest/no driver |
| `dn` | driver name | string/null | `null` for guest/no driver |
| `a` | avatar URL | string/null | opaque server-side download URL, valid for at most one hour |
| `b` | best lap time ms | integer/null | fastest valid lap in milliseconds |

`ve.i`, `rc.i`, and `di` are stable for a venue's endpoint and do not change when its URL is edited or its signing secret is rotated. IDs are generated separately for each venue's endpoint, so the same driver has different `di` values at different venues. `vi` in `rr`/`rl` equals `ve.i` in `rf`.

V1 emits only valid results. DNS, DNF, and DQ results are not emitted. Manual edits after settlement do not emit an update event.

When `a` is non-null, the receiver MUST treat it as a short-lived download URL rather than a stable avatar identifier. It is valid for at most one hour from KartClub's first delivery attempt; retries reuse the exact same URL and do not extend expiration. Schedule a server-side `GET` promptly, accept only the `a.kart.yun` HTTPS host, validate the raster image response, and persist the image under the receiver's own URL. The response uses `Cross-Origin-Resource-Policy: same-origin`, so direct embedding from another browser origin is intentionally blocked. Do not use `HEAD`, alter the token, swap the hostname, or expose this temporary URL as a client asset. HTTP `410` means expired and `404` means invalid. HTTP `502` means the source fetch failed; retry it only a limited number of times and abandon a persistently failing image. Historical unsupported avatar sources can produce `a = null`.

## 8. Rolling events (`rr` and `rl`)

### Lap-based `rolling.return_due_soon` (`rr`)

```json
{
  "t": "rr",
  "v": 1,
  "e": "V2kLm8QpR5xN7cZa",
  "o": "2026-08-20T12:30:00+08:00",
  "r": "nKaLjg6RqgT0bcA0",
  "vi": "DBLwV6V8oFvA1ADo",
  "c": "18",
  "p": { "m": "l", "d": 9, "q": 10, "r": 1 }
}
```

### Time-based `rolling.return_due_soon` (`rr`)

```json
{
  "t": "rr",
  "v": 1,
  "e": "V2kLm8QpR5xN7cZa",
  "o": "2026-08-20T12:30:00+08:00",
  "r": "nKaLjg6RqgT0bcA0",
  "vi": "DBLwV6V8oFvA1ADo",
  "c": "18",
  "p": { "m": "t", "d": 420, "q": 480, "r": 60 }
}
```

### `rolling.purchase_limit_reached` (`rl`)

```json
{
  "t": "rl",
  "v": 1,
  "e": "K9xQm2ZaP7vN4cLs",
  "o": "2026-08-20T12:31:00+08:00",
  "r": "nKaLjg6RqgT0bcA0",
  "vi": "DBLwV6V8oFvA1ADo",
  "c": "18",
  "p": { "m": "l", "d": 10, "q": 10, "r": 0 }
}
```

| Key | Meaning | Type | Description |
|---|---|---|---|
| `vi` | venue ID | string | unique venue ID |
| `c` | race car number | string | integer car number converted to string; leading zero is not guaranteed |
| `p.m` | mode | string | `l` for laps; `t` for time |
| `p.d` | completed | integer | completed laps or elapsed seconds |
| `p.q` | purchased quota | integer | purchased laps or seconds |
| `p.r` | remaining | integer | remaining laps or seconds; may be zero or negative in `rl` |

## 9. Test events

- `webhook.test` / `wt` contains only common fields and validates connectivity, signature handling, and 2xx response handling.
- Simulated `rf`, `rr`, and `rl` events have the same schema as production events and include `x = 1`.
- IDs in simulated events are random and example business values are not real race data.
- `x` is covered by the signature.
- Record simulation results for integration diagnostics, but do not insert simulated events into production business tables.

## 10. Idempotency

Retries preserve the raw body, `e`, and `r`. Enforce `e` uniqueness atomically.

```sql
CREATE TABLE kartclub_webhook_events (
  event_id VARCHAR(16) PRIMARY KEY,
  event_type VARCHAR(2) NOT NULL,
  result_id VARCHAR(16) NOT NULL,
  received_at TIMESTAMP NOT NULL,
  payload JSON NOT NULL
);
```

Use an atomic insert such as `INSERT ... ON CONFLICT DO NOTHING`. Trigger downstream processing only when the first insert succeeds. Do not implement idempotency as a separate read followed by an insert.

## 11. Response and retries

| Result | KartClub behavior |
|---|---|
| HTTP `2xx` | success; no retry |
| network error or timeout | retry |
| HTTP `408`, `425`, or `429` | retry |
| HTTP `5xx` | retry |
| any other HTTP `3xx` or `4xx` | final failure; no retry |

Maximum attempts:

1. Immediately after the event.
2. No earlier than approximately 2 seconds after the first failure.
3. No earlier than approximately 10 seconds after the second failure.

A valid `Retry-After` on HTTP 429 may be honored up to 1 hour. Delivery is best effort. V1 has no historical replay API, and even a short receiver outage may exhaust all three attempts. Repeated final failures can automatically suspend the endpoint.

## 12. Avatar download security

The `a` field is a source URL for server-side download. Cache the image in customer-controlled storage; do not make browser or app clients depend on the source URL.

The downloader MUST:

- accept only public HTTPS URLs;
- resolve DNS and reject all private, loopback, link-local, and reserved target addresses;
- disable redirects, or repeat DNS/address validation for every redirect hop;
- limit response size, Content-Type, total download time, and decoded pixel dimensions;
- ignore untrusted file names and extensions from the URL;
- avoid logging unnecessary personal data.

## 13. Acceptance checklist

- [ ] Public HTTPS endpoint is reachable and does not require redirects.
- [ ] Raw body is captured before JSON parsing.
- [ ] Timestamp format and 300-second freshness window are validated.
- [ ] Signature uses the decoded key and constant-time comparison.
- [ ] Fixed signature vector and negative signature cases pass.
- [ ] JSON is parsed only after successful validation.
- [ ] `e` has a database uniqueness constraint.
- [ ] Duplicate deliveries do not repeat business side effects.
- [ ] `r` correlates events but is not used for event idempotency.
- [ ] `x = 1` events stay outside production business tables.
- [ ] Durable acceptance occurs before returning 2xx.
- [ ] Avatar downloads implement the required SSRF and resource limits.
- [ ] `wt` and every subscribed business event have been tested.
- [ ] Unknown additional fields are ignored.
- [ ] Unsupported `v` values are rejected and alerted.

请读取 https://kart.club/docs/webhooks/agent.md，并按文档实现 KartClub Webhook V1 接收端。

快速开始

为每个车场向 KartClub 对接人员提供一个公网可访问的 HTTPS Webhook 地址。
保存开通时一次性显示的签名密钥。
在服务端保留原始请求体，校验时间戳和 HMAC-SHA256 签名。
使用字段 e 作为事件幂等键，同一个 e 只处理一次。
数据安全落库后返回 HTTP 2xx，推荐 204 No Content。
先发送连通性测试，再发送各订阅事件的模拟数据。

接收地址要求：使用公开 CA 签发证书的公网 HTTPS 地址；不得依赖重定向；建议在 2 秒内返回。KartClub 建立连接最多等待 2 秒，任一次响应读取最多等待 5 秒，整个请求最多等待 8 秒。

每个车场一个地址：每个接收地址对应一把签名密钥。同时服务多家车场时，请为每家车场提供不同的地址（例如用 path 区分），收到请求时按地址即可确定用哪把密钥验签。

事件

中文名称	英文事件名	`t`	触发条件
连通性测试	`webhook.test`	`wt`	管理员手动发送，只验证接收链路
完赛成绩	`race.result_finalized`	`rf`	有效比赛成绩完成结算
收车提醒	`rolling.return_due_soon`	`rr`	距购买圈数 1 圈，或距购买时长 60 秒
超圈提醒	`rolling.purchase_limit_reached`	`rl`	达到或超过购买圈数或购买时长

同一比赛成绩可能产生多个事件。使用 e 去重，使用 r 关联同一成绩；不要使用 r 作为事件幂等键。

事件不保证按发生顺序到达，例如 rl 等待重试期间，rf 可能先到。o 在重试时保持不变，可用于判断事件实际发生的先后。

HTTP 请求

POST /kartclub/webhooks HTTP/1.1
Host: hooks.example.com
Content-Type: application/json; charset=utf-8
User-Agent: KartClub-Webhook/1.0
X-KC-Timestamp: 1787196896
X-KC-Signature: v1.ESQi38l2tpSgp6ToapkbI9nEpmioQL8z_aIzMeo-NnY

{"t":"wt","v":1,"e":"abcdefghijklmnop","o":"2026-08-20T12:34:56+08:00","r":"ponmlkjihgfedcba"}

请求头	值或说明
`Content-Type`	`application/json; charset=utf-8`
`User-Agent`	`KartClub-Webhook/1.0`
`X-KC-Timestamp`	发送时的 Unix 秒时间戳
`X-KC-Signature`	`v1.` + 无 padding Base64URL HMAC-SHA256

签名验证

读取 X-KC-Timestamp 和 X-KC-Signature。
拒绝与当前时间相差超过 300 秒的时间戳。
保留框架解析前的原始 body 字节，不要重新序列化 JSON。
将签名密钥做 Base64URL 解码。
计算 HMAC-SHA256(key, timestamp + "." + raw_body)。
将摘要编码为无 padding Base64URL，并加上 v1. 前缀。
使用恒定时间比较签名；通过后再解析 JSON。

timestamp_value = Integer(timestamp, exception: false)
fresh = timestamp_value &&
  (Time.now.to_i - timestamp_value).abs <= 300

valid = false
if fresh
  raw_key = Base64.urlsafe_decode64(signing_secret)
  digest = OpenSSL::HMAC.digest(
    "SHA256", raw_key, "#{timestamp}.#{raw_body}"
  )
  expected = "v1.#{Base64.urlsafe_encode64(digest, padding: false)}"
  received = signature.to_s
  valid = expected.bytesize == received.bytesize &&
    ActiveSupport::SecurityUtils.secure_compare(expected, received)
end

const key = Buffer.from(signingSecret, "base64url")
const digest = crypto.createHmac("sha256", key)
  .update(Buffer.from(`${timestamp}.`, "utf8"))
  .update(rawBody)
  .digest("base64url")

const expected = Buffer.from(`v1.${digest}`, "utf8")
const received = Buffer.from(signature || "", "utf8")
const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300
const valid = fresh && expected.length === received.length &&
  crypto.timingSafeEqual(expected, received)

valid = False
if isinstance(timestamp, str) and timestamp.isascii() and timestamp.isdigit():
    fresh = abs(int(time.time()) - int(timestamp)) <= 300
    if fresh:
        padding = "=" * (-len(signing_secret) % 4)
        key = base64.urlsafe_b64decode(signing_secret + padding)
        message = timestamp.encode() + b"." + raw_body
        digest = hmac.new(key, message, hashlib.sha256).digest()
        encoded = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
        expected = f"v1.{encoded}"
        received = (signature or "").encode("utf-8", errors="replace")
        valid = hmac.compare_digest(expected.encode("ascii"), received)

固定测试向量

secret    = MDEyMzQ1Njc4OWFiY2RlZjAxMjM0NTY3ODlhYmNkZWY
timestamp = 1787196896
body      = {"t":"wt","v":1,"e":"abcdefghijklmnop","o":"2026-08-20T12:34:56+08:00","r":"ponmlkjihgfedcba"}
signature = v1.ESQi38l2tpSgp6ToapkbI9nEpmioQL8z_aIzMeo-NnY

公共字段

Payload 为 UTF-8 紧凑 JSON，字段名使用固定短码。

Key	完整含义	类型	说明
`t`	event type	string	`wt` / `rf` / `rr` / `rl`
`v`	event version	integer	V1 固定为 `1`
`e`	event ID	string	16 字符，事件幂等键
`o`	occurred at	string	当前事件的触发时间；ISO 8601，带时区
`r`	result ID	string	16 字符，成绩关联键
`x`	test marker	integer	可选；`1` 表示模拟数据

o 具体代表：wt 为管理员发送测试的时间，rf 为成绩结算完成时间，rr/rl 为达到提醒条件的时间。

完赛成绩

race.result_finalized · t = rf

{
  "t": "rf",
  "v": 1,
  "e": "FzxY8W2jPa3kLm9Q",
  "o": "2026-08-20T12:34:56+08:00",
  "r": "nKaLjg6RqgT0bcA0",
  "s": "2026-08-20T12:24:20+08:00",
  "f": "2026-08-20T12:34:20+08:00",
  "ve": { "i": "DBLwV6V8oFvA1ADo", "n": "示例车场" },
  "rc": { "i": "f07ELvqKvP4QwFjJ", "n": "成人竞速" },
  "di": "qgP7YieaW9oUW1xG",
  "dn": "车手昵称",
  "a": "https://a.kart.yun/BGqSn5AAAQIDBAUGBxnlf_fDiS0GmcK8Mg9a1duRELjZJfZ-YEgIWE7uIoulSQ",
  "b": 52341
}

Key	完整含义	类型	说明
`s`	started at	string	比赛记录开始时间（滚动模式为发车时间）；ISO 8601，带时区
`f`	finished at	string	完赛时间，ISO 8601，带时区
`ve.i`	venue ID	string	车场唯一 ID
`ve.n`	venue name	string	车场名称
`rc.i`	race class ID	string	车型/组别唯一 ID
`rc.n`	race class name	string	车型/组别名称
`di`	driver ID	string/null	车手唯一 ID；游客为 `null`
`dn`	driver name	string/null	车手昵称；游客为 `null`
`a`	avatar URL	string/null	最长 1 小时有效的加密头像下载地址
`b`	best lap time ms	integer/null	最快有效圈，毫秒

ve.i、rc.i、di 在同一车场的接入下长期不变，修改接收地址或轮换签名密钥都不会改变；ID 按每个车场的接入分别生成，同一车手在不同车场的 di 不同。rr/rl 中的 vi 与 ve.i 是同一个值。

V1 只发送有效成绩；DNS、DNF、DQ 不发送。结算后的人工修改不会再次推送更新事件。

滚动模式提醒

收车提醒

rolling.return_due_soon · t = rr

{
  "t": "rr",
  "v": 1,
  "e": "V2kLm8QpR5xN7cZa",
  "o": "2026-08-20T12:30:00+08:00",
  "r": "nKaLjg6RqgT0bcA0",
  "vi": "DBLwV6V8oFvA1ADo",
  "c": "18",
  "p": { "m": "l", "d": 9, "q": 10, "r": 1 }
}

时间票使用同一结构：p = { "m": "t", "d": 420, "q": 480, "r": 60 }。

超圈提醒

rolling.purchase_limit_reached · t = rl

{
  "t": "rl",
  "v": 1,
  "e": "K9xQm2ZaP7vN4cLs",
  "o": "2026-08-20T12:31:00+08:00",
  "r": "nKaLjg6RqgT0bcA0",
  "vi": "DBLwV6V8oFvA1ADo",
  "c": "18",
  "p": { "m": "l", "d": 10, "q": 10, "r": 0 }
}

Key	完整含义	类型	说明
`vi`	venue ID	string	车场唯一 ID
`c`	race car number	string	整数车号转成字符串，不保证前导零
`p.m`	mode	string	`l` 圈数；`t` 时间
`p.d`	completed	integer	已完成圈数或已使用秒数
`p.q`	purchased quota	integer	购买圈数或购买秒数
`p.r`	remaining	integer	剩余圈数或秒数，可能为 0 或负数

测试事件

连通性测试：webhook.test / wt，只包含公共字段。
业务格式模拟：可选择 rf、rr 或 rl；结构与正式事件一致，并包含 x = 1。

x = 1 的数据只用于联调，不应写入正式业务表。

幂等处理

同一事件可能重复送达。请以 e 作为数据库唯一键并原子写入；只有首次写入成功时执行业务操作，重复 e 直接返回 2xx。

返回值与重试

结果	KartClub 行为
HTTP `2xx`	接收成功，不再重试
网络错误或超时	自动重试
HTTP `408` / `425` / `429`	自动重试
HTTP `5xx`	自动重试
其他 HTTP `3xx` / `4xx`	直接记为失败，不重试

最多尝试 3 次：立即、最快约 2 秒后、最快约 10 秒后。HTTP 429 返回的合法 Retry-After 最长采纳 1 小时。

V1 为 best effort，不提供历史补发接口。接收端短时不可用也可能在三次尝试用尽后漏收事件；连续多次最终失败时，接收地址可能自动暂停。

头像地址

字段 a 是加密的临时下载地址，只允许 GET，从 KartClub 第一次实际投递起最长 1 小时有效；重试不会刷新有效期。响应会阻止其他浏览器来源直接嵌入，需要保留头像时，请在有效期内由服务器下载。

地址的 host 固定为 a.kart.yun，path 是单段 Base64URL token；替换域名、添加 query 或修改 token 都会导致访问失败。
过期地址返回 HTTP 410；无效或被篡改的地址返回 404。

版本兼容

V1 的 v 固定为 1。
接收方应忽略无法识别的额外字段，但不得忽略未知的 v。
收到不支持的 v 时，应告警并返回非 2xx。
不兼容变更会提升协议版本并另行通知。