Cảnh báo và giới hạn
Mỗi cảnh báo theo dõi giá giao ngay của một kim loại, vàng, bạc hoặc đồng, với một quy tắc và gửi đến một URL. Plus và Pro đều có 5 cảnh báo mỗi gói. Free và Basic không có cảnh báo giá. Nếu gói hết hạn hoặc thanh toán thất bại, việc gửi sẽ dừng cho đến khi gói hoạt động trở lại.
- Vượt mức giá: giá chuyển từ một phía của mức giá sang phía còn lại, theo hướng lên, xuống hoặc cả hai. Sau khi kích hoạt, cảnh báo im lặng trong ít nhất 10 phút. Nếu giá vượt mức theo hướng ngược lại rồi quay về trong thời gian đó, lần vượt thứ hai sẽ không được gửi. Cảnh báo chỉ sẵn sàng kích hoạt lại khi thời gian đó đã qua và giá đã quay về phía ban đầu trước lần vượt, vượt qua mức giá theo hướng ngược lại một khoảng 0.1%. Nhờ vậy, lần vượt mức thực sự tiếp theo vẫn được gửi, còn dao động nhỏ quanh mức giá được bỏ qua.
- Biến động theo tỷ lệ: giá thay đổi theo một tỷ lệ phần trăm trong 1 giờ hoặc 24 giờ. Cảnh báo kích hoạt một lần. Sau 1 giờ, khi mức biến động đã giảm xuống dưới ngưỡng, cảnh báo sẵn sàng kích hoạt lại. Biến động 24 giờ ngay sau khi thị trường mở cửa đầu tuần được tính từ giá mở cửa trở lại. Chênh lệch giá cuối tuần không bao giờ được tính là biến động.
- Giá đóng cửa hằng ngày: giá cuối cùng của ngày UTC, được gửi ngay sau nửa đêm UTC. Kim loại không có giá trong ngày đó, chẳng hạn vào cuối tuần, sẽ không có giá đóng cửa.
Ngày được tính theo UTC. Cảnh báo giá đóng cửa hằng ngày được gửi một lần mỗi ngày. Khi giá dao động quanh một mức, hệ thống không gửi yêu cầu cho mỗi lần cập nhật giá.
Các sự kiện bạn có thể nhận
price.level_cross: giá đã vượt mức bạn đặt.price.percent_move: giá đã biến động theo tỷ lệ phần trăm bạn đặt.price.daily_close: ngày UTC đã kết thúc.webhook.test: bạn đã nhấn Send test trên một cảnh báo. Giá trịdatalà{"alert_id":"<alert id>"}. Bạn có thể gửi một lần thử cho mỗi cảnh báo mỗi phút và tối đa 20 lần thử có thể chờ gửi cùng lúc.
Đọc yêu cầu
Bạn nhận một POST tại URL của mình. URL phải dùng https://, cổng 443 và tên máy chủ công khai, không có tên người dùng hay mật khẩu và dài không quá 2048 ký tự. Địa chỉ được kiểm tra trước mỗi lần gửi. Hệ thống không đi theo chuyển hướng và phản hồi 3xx được tính là thất bại. Hệ thống chỉ đọc mã trạng thái của bạn.
Phần thân là JSON với bốn trường cấp cao nhất: id, type, created_at và data. Thứ tự khóa và khoảng trắng trong phần thân thực tế có thể khác với các ví dụ ở đây.
- idstring
- Mã định danh duy nhất của sự kiện. Dùng để bỏ qua sự kiện trùng lặp.
- typestring
- Một trong các loại sự kiện ở trên.
- created_atstring
- Thời gian UTC theo ISO 8601, kết thúc bằng
Z. Với giá đóng cửa hằng ngày, giá trị này là 23:59:59 của ngày vừa kết thúc. - data.alert_idstring
- Cảnh báo đã kích hoạt. Giá trị này không đổi khi bạn thay khóa bí mật.
- data.kindstring
level_cross,percent_movehoặcdaily_close.- data.symbolstring
XAU-USD-SPOT,XAG-USD-SPOThoặcHG-USD-SPOT.- data.directionstring
above,belowhoặceither, theo thiết lập của cảnh báo.- data.pricestring
- Giá kích hoạt cảnh báo, dưới dạng chuỗi số thập phân. Chỉ có trong sự kiện mức giá và tỷ lệ phần trăm.
- data.observed_atstring
- Thời điểm ghi nhận giá. Chỉ có trong sự kiện mức giá và tỷ lệ phần trăm.
- data.levelstring
- Mức giá bạn đặt. Chỉ có trong sự kiện mức giá.
- data.percent, data.window, data.reference_pricestring
- Tỷ lệ phần trăm bạn đặt, khoảng thời gian (
1hhoặc24h) và giá đầu khoảng thời gian đó. Chỉ có trong sự kiện tỷ lệ phần trăm. - data.date, data.closestring
- Ngày UTC và giá cuối cùng của ngày đó. Chỉ có trong sự kiện giá đóng cửa hằng ngày.
Ví dụ phần thân yêu cầu
price.level_cross
{
"id": "evt_3f0c6a52-6a2e-4b8e-9c1d-2f4b7e9a1c03_level_cross:492841",
"type": "price.level_cross",
"created_at": "2026-10-23T14:02:11.482113Z",
"data": {
"alert_id": "3f0c6a52-6a2e-4b8e-9c1d-2f4b7e9a1c03",
"kind": "level_cross",
"symbol": "XAU-USD-SPOT",
"direction": "above",
"price": "4203.1",
"level": "4200",
"observed_at": "2026-10-23T14:02:11.482113+00:00"
}
}price.percent_move
{
"id": "evt_8a1d52c4-0b7e-4f55-a3d9-61e2c7b8f410_percent_move:492855",
"type": "price.percent_move",
"created_at": "2026-10-23T09:15:40.120934Z",
"data": {
"alert_id": "8a1d52c4-0b7e-4f55-a3d9-61e2c7b8f410",
"kind": "percent_move",
"symbol": "XAU-USD-SPOT",
"direction": "either",
"price": "4168.8",
"percent": "2",
"window": "24h",
"reference_price": "4083.05",
"observed_at": "2026-10-23T09:15:40.120934+00:00"
}
}price.daily_close
{
"id": "evt_c92e0f7b-31a4-4d6a-8e57-a05b3d1c92e8_close:2026-10-22",
"type": "price.daily_close",
"created_at": "2026-10-22T23:59:59Z",
"data": {
"alert_id": "c92e0f7b-31a4-4d6a-8e57-a05b3d1c92e8",
"kind": "daily_close",
"symbol": "XAG-USD-SPOT",
"direction": "either",
"date": "2026-10-22",
"close": "48.62"
}
}webhook.test
{
"id": "evt_test_1792143012345",
"type": "webhook.test",
"created_at": "2026-10-23T09:30:12.345000Z",
"data": {
"alert_id": "3f0c6a52-6a2e-4b8e-9c1d-2f4b7e9a1c03"
}
}Xác minh chữ ký
Kiểm tra Webhook-Signature trước khi xử lý sự kiện. Dùng các byte thô của phần thân đúng như đã nhận. Không phân tích rồi tuần tự hóa lại JSON trước khi kiểm tra.
- Tách
Webhook-Signaturetheo dấu phẩy để đọctvàv1. - Từ chối yêu cầu nếu
tnhanh hoặc chậm hơn đồng hồ của bạn quá 300 giây. - Tạo thông điệp từ
t, một dấu chấm và phần thân thô:<t>.rồi đến phần thân. - Tính HMAC-SHA256 của thông điệp bằng khóa bí mật ký của cảnh báo, bắt đầu bằng
whsec_, rồi mã hóa kết quả dưới dạng thập lục phân. - So sánh kết quả với
v1bằng phép so sánh có thời gian thực thi cố định. Từ chối yêu cầu nếu hai giá trị khác nhau.
Node.js
Python
import { createHmac, timingSafeEqual } from "node:crypto";
import { createServer } from "node:http";
const TOLERANCE_SECONDS = 300;
// rawBody: the request body exactly as received (a Buffer), before any JSON parsing.
function verifyWebhook(rawBody, header, secret, now = Math.floor(Date.now() / 1000)) {
const fields = {};
for (const part of String(header ?? "").split(",")) {
const i = part.indexOf("=");
if (i > 0) fields[part.slice(0, i).trim()] = part.slice(i + 1).trim();
}
const t = Number(fields.t);
if (!Number.isInteger(t) || Math.abs(now - t) > TOLERANCE_SECONDS) return false;
const expected = createHmac("sha256", secret).update(t + ".").update(rawBody).digest();
const given = Buffer.from(fields.v1 ?? "", "hex");
return given.length === expected.length && timingSafeEqual(given, expected);
}
const seen = new Set(); // use your database in production
createServer((req, res) => {
const chunks = [];
req.on("data", (chunk) => chunks.push(chunk));
req.on("end", () => {
const rawBody = Buffer.concat(chunks);
const header = req.headers["webhook-signature"];
if (!verifyWebhook(rawBody, header, process.env.WEBHOOK_SECRET)) {
res.writeHead(400).end();
return;
}
const event = JSON.parse(rawBody);
if (!seen.has(event.id)) {
seen.add(event.id);
// Hand the event to a queue or background job here, then answer quickly.
console.log(event.type, event.data);
}
res.writeHead(204).end();
});
}).listen(Number(process.env.PORT ?? 3000));import hashlib
import hmac
import time
TOLERANCE_SECONDS = 300
def verify_webhook(raw_body: bytes, header: str, secret: str, now: int | None = None) -> bool:
"""raw_body is the request body exactly as received, before any JSON parsing."""
fields = dict(p.strip().split("=", 1) for p in (header or "").split(",") if "=" in p)
try:
t = int(fields["t"])
except (KeyError, ValueError):
return False
now = int(time.time()) if now is None else now
if abs(now - t) > TOLERANCE_SECONDS:
return False
signed = f"{t}.".encode() + raw_body
expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
return hmac.compare_digest(fields.get("v1", "").encode(), expected.encode())
# Flask: verify_webhook(request.get_data(), request.headers.get("Webhook-Signature", ""), secret)
# Django: verify_webhook(request.body, request.headers.get("Webhook-Signature", ""), secret)Phản hồi và xử lý các lần thử lại
Trả về mã 2xx bất kỳ trong vòng 10 giây. Phản hồi 3xx, 4xx, 5xx, hết thời gian chờ hoặc lỗi kết nối đều được tính là một lần thử thất bại. Lưu sự kiện và phản hồi nhanh, rồi thực hiện tác vụ chậm ở chế độ nền.
- Lần thử lại thứ nhất: 1 phút sau lần thất bại đầu tiên.
- Lần thử lại thứ hai: 5 phút sau lần thất bại trước đó.
- Lần thử lại thứ ba: 30 phút sau lần thất bại trước đó.
- Lần thử lại thứ tư: 2 giờ sau lần thất bại trước đó.
- Lần thử lại thứ năm và cuối cùng: 6 giờ sau lần thất bại trước đó.
Tổng cộng là 6 lần thử trong khoảng 8.5 giờ. Sau lần thử cuối cùng thất bại, sự kiện không được gửi lại và không có phương án dự phòng qua thư điện tử. Mỗi lần thử được ký lại với dấu thời gian mới. Sự kiện đã quá một giờ tại thời điểm thử gửi lần đầu sẽ bị loại bỏ. Lịch sử gửi được lưu trong 30 ngày.
Thay khóa bí mật ký
Khóa bí mật chỉ hiển thị một lần khi bạn thêm cảnh báo. Nếu nghi khóa đã bị lộ hoặc bạn làm mất khóa, chọn Rotate secret trên cảnh báo trong bảng điều khiển. Khóa mới chỉ hiển thị một lần. Cảnh báo giữ nguyên mã định danh, khóa cũ ngừng hoạt động ngay lập tức và các lần gửi từ đó dùng khóa mới. Để tránh gửi thất bại, hãy cho máy chủ chấp nhận cả hai khóa trong vài phút khi chuyển đổi.
Câu hỏi
Tôi cần gói nào để dùng cảnh báo giá?
Gói Plus ($39/tháng) và Pro ($89/tháng) đều bao gồm 5 cảnh báo giá cho mỗi gói. Cảnh báo giá không được cung cấp trong gói Free và Basic.
Một cảnh báo có thể được kích hoạt bao lâu một lần?
Sau khi kích hoạt, cảnh báo mức giá không gửi thông báo trong ít nhất 10 phút; các lần vượt mức trong thời gian đó không được gửi. Cảnh báo chỉ sẵn sàng kích hoạt lại khi thời gian đó đã qua và giá đã quay về phía ban đầu trước lần vượt, vượt qua mức giá theo hướng ngược lại một khoảng 0.1%. Cảnh báo tỷ lệ phần trăm kích hoạt một lần, rồi sẵn sàng lại sau 1 giờ khi hết biến động. Giá đóng cửa được gửi mỗi ngày UTC một lần.
Điều gì xảy ra nếu máy chủ của tôi ngừng hoạt động?
Lần gửi thất bại được thử lại tối đa 5 lần nữa trong khoảng 8.5 giờ. Sau lần thử cuối cùng thất bại, sự kiện không được gửi lại và không có phương án dự phòng qua thư điện tử.
Tôi có thể nhận cùng một sự kiện hai lần không?
Có. Lần gửi có thể được thử lại dù bạn đã xử lý, chẳng hạn khi phản hồi của bạn đến sau 10 giây. Hãy lưu mã định danh của các sự kiện đã xử lý và bỏ qua sự kiện trùng lặp.
Xem thêm
- /docs/stream : giá trực tiếp qua WebSocket và SSE
- /pricing : các gói và giới hạn