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.

POST

JSON delivery

10s

Response timeout

2xx

Successful response

Retry and safety policy

Failed events receive up to three total attempts with delays of 0, 5, and 30 seconds.
After five consecutive failed events, the webhook is automatically disabled.
Verify the signature against the exact raw request body before parsing JSON.

Available events

Available Events

link.created

Fired when a new link is created

link.updated

Fired when a link's URL or title is changed

link.archived

Fired when a link is archived

link.clicked

Fired on each redirect (per-click event)

microsite.published

Fired when a microsite is published

qr.scanned

Fired 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.

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

Delivery headers

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

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('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
Go to Dashboard → Developer → Webhooks and click Add Webhook.
2
Enter your HTTPS endpoint URL and select the events you want to subscribe to.
3
Copy the webhook secret, it is shown only once.
4
In your server, verify the X-SID-Signature header before processing.
5
Return HTTP 2xx within 10 seconds. Failed deliveries are retried up to 3 times; after 5 consecutive failed deliveries the webhook is automatically disabled.

Add a Webhook

Ready to start building?

Create an API key in minutes. Free tier included, no credit card required.

Get your API key