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.

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

link.createdFired when a new link is created

link.updatedFired when a link's URL or title is changed

link.archivedFired when a link is archived

link.clickedFired on each redirect (per-click event)

microsite.publishedFired when a microsite is published

qr.scannedFired when a QR code is scanned

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.

{
  "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"
}

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('crypto');

function verifySignature(secret, rawBody, sigHeader) {
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(sigHeader),
    Buffer.from(expected),
  );
}

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

1Vào Dashboard → Developer → Webhooks và nhấp Thêm Webhook.
2Nhập URL endpoint HTTPS của bạn và chọn các sự kiện bạn muốn đăng ký.
3Sao chép webhook secret — nó chỉ hiển thị một lần.
4Trong server của bạn, xác minh header X-SID-Signature trước khi xử lý.
5Trả 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 Nền tảng nhà phát triển