Trình đơn

Webhook cảnh báo giá

Nhận yêu cầu POST có chữ ký tại URL của bạn khi giá vàng, bạc hoặc đồng vượt một mức, biến động theo tỷ lệ phần trăm hoặc chốt ngày. Thêm cảnh báo trong bảng điều khiển, xác minh từng yêu cầu rồi xử lý.

Plus · $39/moPro · $89/mo

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ị data là {"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.

Content-Type: application/jsonUser-Agent: webhook-delivery/1Webhook-Signature: t=<unix seconds>,v1=<hex>

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_move hoặc daily_close.
data.symbolstring
XAU-USD-SPOT, XAG-USD-SPOT hoặc HG-USD-SPOT.
data.directionstring
above, below hoặc either, 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 (1h hoặc 24h) 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.

  1. Tách Webhook-Signature theo dấu phẩy để đọc t và v1.
  2. Từ chối yêu cầu nếu t nhanh hoặc chậm hơn đồng hồ của bạn quá 300 giây.
  3. 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.
  4. 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.
  5. So sánh kết quả với v1 bằ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