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ộ).
Request gửi tới bạn
POST,Content-Type: application/json, timeout 10 giây.- Trả bất kỳ mã
2xxnà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ùngidcùngstatuscủa job để bỏ qua bản trùng. webhook_urlphải làhttpsvà 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> |
{
"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:
- Tách header
Sota-Signaturetheo dấu phẩy thành các cặpkhóa=giá trị: mộttvàv1. - Từ chối nếu
tlệch quá 300 giây (5 phút) so với đồng hồ của bạn, để chặn gửi lại (replay). - 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. - 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ọiv1và 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).
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);
// });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à:
Sota-Signature: t=1700000000,v1=4044b40e2ed61a4a5d8b323195ea2d1baaf45514a41961c6e74d4a9c7e2563e8Dùng vector này trong unit test của bạn (nhớ cố định đồng hồ, vì t đã cũ).