Chuyển đến nội dung chính
s.id Logo
Nền tảng nhà phát triển

Webhooks

Gửi sự kiện thời gian thực đến endpoint HTTPS của bạn.

Tổng quan

Đăng ký endpoint HTTPS công khai tại Dashboard → Developer → Webhooks. s.id sẽ POST payload JSON đã ký đến URL của bạn khi sự kiện đã đăng ký xảy ra. Các lần gửi thất bại (không phải 2xx hoặc timeout) sẽ được thử lại tối đa 3 lần, với độ trễ 0 giây, 5 giây và 30 giây.

POST

Phân phối JSON

10s

Thời gian chờ phản hồi

2xx

Phản hồi thành công

Chính sách thử lại và an toàn

  • Sự kiện lỗi được thử tối đa ba lần, với khoảng chờ 0, 5 và 30 giây.
  • Sau năm sự kiện lỗi liên tiếp, webhook sẽ tự động bị vô hiệu hóa.
  • Xác minh chữ ký với phần thân yêu cầu thô chính xác trước khi phân tích JSON.

Các sự kiện có sẵn

Các sự kiện có sẵn

link.created

Kích hoạt khi liên kết mới được tạo

link.updated

Kích hoạt khi URL hoặc tiêu đề liên kết thay đổi

link.archived

Kích hoạt khi một liên kết được lưu trữ

link.clicked

Kích hoạt ở mỗi lần chuyển hướng (một sự kiện cho mỗi lượt nhấp)

microsite.published

Kích hoạt khi microsite được xuất bản

qr.scanned

Kích hoạt khi mã QR được quét

Cấu trúc Payload

Mỗi POST webhook chứa phần thân JSON với tên sự kiện, tài nguyên liên quan và dấu thời gian UTC.

application/json
{
  "event": "link.created",
  "link": {
    "id": 123,
    "short": "mylink",
    "short_url": "https://s.id/mylink",
    "long_url": "https://example.com/long-url",
    "title": "My Link",
    "created": "2026-06-22T10:00:00Z"
  },
  "timestamp": "2026-06-22T10:00:00Z"
}

Header phân phối

X-SID-Event
Tên sự kiện
X-SID-Signature
Chữ ký sha256=<hmac-hex>
X-SID-Delivery-ID
Mã định danh lần gửi duy nhất
User-Agent
s.id-Webhooks/1.0

Xác minh chữ ký

Mỗi lần gửi có header X-SID-Signature: sha256=<hex>. Tính HMAC-SHA256 của phần thân request thô bằng secret webhook của bạn và so sánh bằng timing-safe equality.

Luôn xác minh chữ ký trước khi xử lý sự kiện. Đừng bao giờ tin tưởng payload mà không xác minh HMAC.
Node.js
const crypto = require('node:crypto');

function verifySignature(secret, rawBody, sigHeader) {
  if (typeof sigHeader !== 'string' || !sigHeader.startsWith('sha256=')) {
    return false;
  }

  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const receivedBuffer = Buffer.from(sigHeader, 'utf8');
  const expectedBuffer = Buffer.from(expected, 'utf8');

  return receivedBuffer.length === expectedBuffer.length &&
    crypto.timingSafeEqual(receivedBuffer, expectedBuffer);
}
Go
func verifySignature(secret, body []byte, sig string) bool {
  mac := hmac.New(sha256.New, secret)
  mac.Write(body)
  expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
  return hmac.Equal([]byte(sig), []byte(expected))
}

Thiết lập

  1. 1

    Vào Dashboard → Developer → Webhooks và nhấp Thêm Webhook.

  2. 2

    Nhập URL endpoint HTTPS của bạn và chọn các sự kiện bạn muốn đăng ký.

  3. 3

    Sao chép webhook secret, nó chỉ hiển thị một lần.

  4. 4

    Trong server của bạn, xác minh header X-SID-Signature trước khi xử lý.

  5. 5

    Trả về HTTP 2xx trong vòng 10 giây. Các lần gửi thất bại sẽ được thử lại tối đa 3 lần; sau 5 lần gửi thất bại liên tiếp, webhook sẽ tự động bị vô hiệu hóa.

Thêm Webhook

Sẵn sàng bắt đầu xây dựng?

Tạo API key trong vài phút. Đã có gói miễn phí, không cần thẻ tín dụng.

Lấy API key của bạn