Webhooks

Penghantaran acara masa nyata ke titik akhir HTTPS anda.

Gambaran Keseluruhan

Daftarkan titik akhir HTTPS awam di Dashboard → Pembangun → Webhooks. s.id akan POST muatan JSON bertanda tangan ke URL anda apabila acara yang dilanggan berlaku. Penghantaran yang gagal (bukan 2xx atau tamat masa) akan dicuba semula sehingga 3 kali, dengan lengah 0 saat, 5 saat, dan 30 saat.

POST

Penghantaran JSON

10s

Had masa respons

2xx

Respons berjaya

Dasar percubaan semula dan keselamatan

Peristiwa yang gagal menerima sehingga tiga percubaan keseluruhan dengan sela 0, 5 dan 30 saat.
Selepas lima peristiwa gagal berturut-turut, webhook dinyahdayakan secara automatik.
Sahkan tandatangan terhadap badan permintaan mentah yang tepat sebelum menghurai JSON.

Acara yang tersedia

Acara yang Tersedia

link.created

Dicetuskan apabila pautan baharu dicipta

link.updated

Dicetuskan apabila URL atau tajuk pautan diubah

link.archived

Dicetuskan apabila pautan diarkibkan

link.clicked

Dicetuskan pada setiap pengalihan (peristiwa setiap klik)

microsite.published

Dicetuskan apabila microsite diterbitkan

qr.scanned

Dicetuskan apabila kod QR diimbas

Struktur Muatan

Setiap POST webhook mengandungi badan JSON dengan nama acara, sumber yang berkaitan, dan cap waktu 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"
}

Pengepala penghantaran

X-SID-Event: Nama peristiwa
X-SID-Signature: Tandatangan sha256=<hmac-hex>
X-SID-Delivery-ID: Pengenal penghantaran unik
User-Agent: s.id-Webhooks/1.0

Mengesahkan Tandatangan

Setiap penghantaran menyertakan pengepala X-SID-Signature: sha256=<hex>. Kira HMAC-SHA256 badan permintaan mentah menggunakan rahsia webhook anda dan bandingkan dengan kesetaraan selamat-masa.

Sentiasa sahkan tandatangan sebelum memproses acara. Jangan sesekali mempercayai muatan tanpa mengesahkan 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);
}

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))
}

Persediaan

1
Pergi ke Dashboard → Pembangun → Webhooks dan klik Tambah Webhook.
2
Masukkan URL titik akhir HTTPS anda dan pilih acara yang ingin anda langgan.
3
Salin rahsia webhook, ia ditunjukkan sekali sahaja.
4
Di pelayan anda, sahkan pengepala X-SID-Signature sebelum memproses.
5
Kembalikan HTTP 2xx dalam 10 saat. Penghantaran yang gagal dicuba semula sehingga 3 kali; selepas 5 kegagalan berturut-turut, webhook akan dilumpuhkan secara automatik.

Tambah Webhook

Bersedia untuk mula membina?

Cipta kunci API dalam beberapa minit. Peringkat percuma disertakan, tiada kad kredit diperlukan.

Dapatkan kunci API anda