Webhooks

Real-time event delivery to your HTTPS endpoint.

Overview

Register a public HTTPS endpoint in Dashboard → Developer → Webhooks. s.id will POST a signed JSON payload to your URL when a subscribed event occurs. Deliveries that fail (non-2xx or timeout) are retried up to 3 times total, with delays of 0s, 5s, and 30s.

Available Events

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

Payload Structure

Every webhook POST contains a JSON body with the event name, the relevant resource, and a UTC timestamp.

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

Verifying Signatures

Every delivery includes an X-SID-Signature: sha256=<hex> header. Compute HMAC-SHA256 of the raw request body using your webhook secret and compare with timing-safe equality.

Always verify the signature before processing the event. Never trust the payload without verifying the 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))
}

Setup

1Go to Dashboard → Developer → Webhooks and click Add Webhook.

2Enter your HTTPS endpoint URL and select the events you want to subscribe to.

3Copy the webhook secret, it is shown only once.

4In your server, verify the X-SID-Signature header before processing.

5Return HTTP 2xx within 10 seconds. Failed deliveries are retried up to 3 times; after 5 consecutive failed deliveries the webhook is automatically disabled.

Developer Platform