# Webhook

Nhận job đã xong qua webhook và xác minh chữ ký Sota-Signature.

Job tạo với `webhook_url` được gửi tới URL đó khi đạt trạng thái cuối (`completed` hoặc `failed`). Body là đối tượng job, giống hệt `GET /v1/audio/speech/jobs/{id}`; tải audio qua endpoint `content` của job (xem [Job bất đồng bộ](/docs-md/async-jobs.md#download)).

## Request gửi tới bạn

- `POST`, `Content-Type: application/json`, timeout 10 giây.
- Trả bất kỳ mã `2xx` nào để xác nhận. Mã khác hoặc timeout sẽ được gửi lại với backoff, tối đa 8 lần. Vì vậy handler phải **idempotent**: dùng `id` cùng `status` của job để bỏ qua bản trùng.
- `webhook_url` phải là `https` và không được trỏ tới địa chỉ nội bộ.

| Header | Giá trị |
|---|---|
| `Sota-Event` | `speech.job.completed` hoặc `speech.job.failed` |
| `Sota-Delivery` | ID của lần gửi; giữ nguyên qua các lần gửi lại cùng sự kiện |
| `Sota-Signature` | `t=<unix seconds>,v1=<hex>` |

```json
{
  "id": "job_01jd8x3k9q4m7n2p5r6s8t0v1w",
  "object": "speech.job",
  "status": "completed",
  "model": "sota-voice-v1",
  "voice": "default",
  "response_format": "mp3",
  "characters": 1840,
  "webhook_url": "https://example.com/hooks/sota",
  "created_at": 1763366400,
  "started_at": 1763366402,
  "completed_at": 1763366431,
  "expires_at": 1763971231,
  "error": null
}
```

## Khóa ký (signing secret)

Mỗi tài khoản có một khóa ký dạng `whsec_...`, xem và tạo lại trong dashboard (**Webhook**). Lưu nó trên server, ví dụ trong biến `SOTA_WEBHOOK_SECRET`. Dùng **nguyên chuỗi** `whsec_...` làm khóa HMAC.

Tạo khóa mới có hiệu lực **ngay lập tức**: khóa cũ ngừng được dùng, và mọi lần gửi sau đó, kể cả các lần gửi lại của sự kiện cũ, đều ký bằng khóa mới. Không có giai đoạn ký song song hai khóa. Để không mất webhook trong lúc triển khai, hãy cho máy chủ nhận chấp nhận **cả khóa cũ lẫn khóa mới** (thử lần lượt từng khóa), tạo khóa mới, rồi gỡ khóa cũ khi đã triển khai xong.

## Xác minh chữ ký

Luôn xác minh trước khi tin body:

1. Tách header `Sota-Signature` theo dấu phẩy thành các cặp `khóa=giá trị`: một `t` và `v1`.
2. Từ chối nếu `t` lệch quá **300 giây** (5 phút) so với đồng hồ của bạn, để chặn gửi lại (replay).
3. Tính HMAC-SHA256 với khóa là khóa ký, trên chuỗi `"<t>.<raw body>"`, ở dạng hex chữ thường.
4. So sánh trong thời gian hằng (constant time). Hiện mỗi header chỉ có đúng một `v1`; các ví dụ dưới đây vẫn đọc mọi `v1` và chấp nhận nếu bất kỳ giá trị nào khớp, để không hỏng nếu sau này header có thêm giá trị.

Dùng **đúng các byte thô** đã nhận, không parse rồi serialize lại JSON (thứ tự field và khoảng trắng sẽ khác, chữ ký sẽ sai).

```js tab="Node.js"
const crypto = require('node:crypto');

const TOLERANCE_SECONDS = 300;

// rawBody must be the exact bytes received (a Buffer), not re-serialised JSON.
function verifySotaSignature(secret, header, rawBody) {
  let t = null;
  const sigs = [];
  for (const part of header.split(',')) {
    const p = part.trim();
    const i = p.indexOf('=');
    if (i < 0) continue;
    const k = p.slice(0, i);
    const v = p.slice(i + 1);
    if (k === 't') {
      if (!/^[+-]?[0-9]+$/.test(v)) return false;
      t = Number(v);
    } else if (k === 'v1') {
      sigs.push(v);
    }
  }
  if (t === null || sigs.length === 0) return false;
  if (Math.abs(Date.now() / 1000 - t) > TOLERANCE_SECONDS) return false;

  const want = Buffer.from(
    crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex'),
  );
  return sigs.some((s) => {
    const got = Buffer.from(s);
    return got.length === want.length && crypto.timingSafeEqual(got, want);
  });
}

// Express: app.post('/sota', express.raw({ type: '*/*' }), (req, res) => {
//   const ok = verifySotaSignature(process.env.SOTA_WEBHOOK_SECRET, req.get('Sota-Signature') ?? '', req.body);
//   res.sendStatus(ok ? 200 : 400);
// });
```

```python tab="Python"
import hashlib
import hmac
import re
import time

TOLERANCE_SECONDS = 300

def verify_sota_signature(secret: str, header: str, raw_body: bytes) -> bool:
    """raw_body must be the exact bytes received, not re-serialised JSON."""
    t = None
    sigs = []
    for part in header.split(","):
        k, sep, v = part.strip().partition("=")
        if not sep:
            continue
        if k == "t":
            if not re.fullmatch(r"[+-]?[0-9]+", v):
                return False
            t = int(v)
        elif k == "v1":
            sigs.append(v)
    if t is None or not sigs:
        return False
    if abs(time.time() - t) > TOLERANCE_SECONDS:
        return False

    want = hmac.new(
        secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return any(hmac.compare_digest(want.encode(), s.encode()) for s in sigs)

# Flask: verify_sota_signature(SECRET, request.headers.get("Sota-Signature", ""), request.get_data())
```

```go tab="Go"
package webhook

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"strconv"
	"strings"
	"time"
)

const tolerance = 300 * time.Second

// body must be the exact bytes received, not re-serialised JSON.
func VerifySotaSignature(secret, header string, body []byte, now time.Time) bool {
	var ts int64
	var haveT bool
	var sigs []string
	for _, part := range strings.Split(header, ",") {
		k, v, ok := strings.Cut(strings.TrimSpace(part), "=")
		if !ok {
			continue
		}
		switch k {
		case "t":
			n, err := strconv.ParseInt(v, 10, 64)
			if err != nil {
				return false
			}
			ts, haveT = n, true
		case "v1":
			sigs = append(sigs, v)
		}
	}
	if !haveT || len(sigs) == 0 {
		return false
	}
	if d := now.Sub(time.Unix(ts, 0)); d > tolerance || d < -tolerance {
		return false
	}

	m := hmac.New(sha256.New, []byte(secret))
	m.Write([]byte(strconv.FormatInt(ts, 10) + "."))
	m.Write(body)
	want := []byte(hex.EncodeToString(m.Sum(nil)))
	for _, s := range sigs {
		if hmac.Equal(want, []byte(s)) {
			return true
		}
	}
	return false
}
```

## Kiểm tra lại

Với khóa `whsec_golden_secret`, body `{"id":"job_golden","status":"completed"}` và `t=1700000000`, chữ ký đúng là:

```text
Sota-Signature: t=1700000000,v1=4044b40e2ed61a4a5d8b323195ea2d1baaf45514a41961c6e74d4a9c7e2563e8
```

Dùng vector này trong unit test của bạn (nhớ cố định đồng hồ, vì `t` đã cũ).

