Webhooks

Real-time na pagpapadala ng event sa iyong HTTPS endpoint.

Pangkalahatang-ideya

Irehistro ang isang pampublikong HTTPS endpoint sa Dashboard → Developer → Webhooks. Mag-POST ang s.id ng naka-sign na JSON payload sa iyong URL kapag nangyari ang naka-subscribe na event. Ang mga nabigong delivery (hindi 2xx o timeout) ay muling susubukan nang hanggang 3 beses, na may pagkaantala na 0 segundo, 5 segundo, at 30 segundo.

POST

JSON delivery

10s

Response timeout

2xx

Matagumpay na response

Patakaran sa retry at seguridad

Ang mga bigong event ay susubukan nang hanggang tatlong beses, na may pagitan na 0, 5, at 30 segundo.
Pagkatapos ng limang sunod-sunod na bigong event, awtomatikong idi-disable ang webhook.
I-verify ang signature laban sa eksaktong raw request body bago i-parse ang JSON.

Mga available na event

Mga Available na Event

link.created

Nati-trigger kapag gumawa ng bagong link

link.updated

Nati-trigger kapag binago ang URL o pamagat ng link

link.archived

Nati-trigger kapag na-archive ang isang link

link.clicked

Nati-trigger sa bawat redirect (event kada click)

microsite.published

Nati-trigger kapag na-publish ang microsite

qr.scanned

Nati-trigger kapag na-scan ang QR code

Istraktura ng Payload

Ang bawat webhook POST ay naglalaman ng JSON body na may pangalan ng event, ang kaugnay na resource, at isang UTC timestamp.

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

Mga delivery header

X-SID-Event: Pangalan ng event
X-SID-Signature: sha256=<hmac-hex> signature
X-SID-Delivery-ID: Natatanging delivery identifier
User-Agent: s.id-Webhooks/1.0

Pag-verify ng mga Signature

Kasama sa bawat delivery ang header na X-SID-Signature: sha256=<hex>. Kalkulahin ang HMAC-SHA256 ng raw request body gamit ang iyong webhook secret at ihambing gamit ang timing-safe equality.

Palaging i-verify ang signature bago iproseso ang event. Huwag kailanman magtiwala sa payload nang hindi na-verify ang 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))
}

Setup

1
Pumunta sa Dashboard → Developer → Webhooks at i-click ang Add Webhook.
2
Ilagay ang iyong HTTPS endpoint URL at piliin ang mga event na gusto mong i-subscribe.
3
Kopyahin ang webhook secret, isang beses lamang itong ipinakikita.
4
Sa iyong server, i-verify ang X-SID-Signature header bago mag-proseso.
5
Mag-return ng HTTP 2xx sa loob ng 10 segundo. Ang mga nabigong delivery ay muling susubukan nang hanggang 3 beses; pagkatapos ng 5 magkakasunod na nabigong delivery, awtomatikong madi-disable ang webhook.

Magdagdag ng Webhook

Handa na bang magsimulang bumuo?

Gumawa ng API key sa loob ng ilang minuto. Kasama ang libreng tier, walang credit card na kailangan.

Kumuha ng iyong API key