Docs menu

Webhooks

Get a signed message at your own address when a link is made, changed or clicked and when a conversion comes in.

Webhooks send a signed message to an address you choose when something happens to your links, so your own tools can react without polling. They are part of the paid plans.

Add an endpoint

Open Webhooks in the members area, add an address that starts with https://, and choose the events you want. The address must be reachable on the public internet. You can have up to 5 endpoints. Each has its own signing secret, shown when you add it and again when you make a new one.

Use Send test on an endpoint to get a webhook.test message straight away.

Events

EventSent when
link.createdA link is created.
link.updatedA link is changed.
link.clickedClicks, sent together once a minute.
conversion.createdA conversion is recorded.
bio.signupSomeone signs up for email on a bio page.
qr.scannedA QR code is scanned, sent together once a minute.

What a message looks like

Every message is a POST with a JSON body. These headers come with it:

  • X-Sizla-Event: the event name.
  • X-Sizla-Delivery: a unique id for this delivery. The same id is used when a message is sent again, so you can ignore repeats.
  • X-Sizla-Signature: the timestamp and signature, for example t=1700000000,v1=3f2a....

The body always has an id, the event, a created_at time and the data:

link.created

JSON
{
    "id": "6f1d2c1e-8a47-4c35-9d0b-2a1c0f5e7b90",
    "event": "link.created",
    "created_at": "2026-11-14T10:02:44+00:00",
    "data": {
        "link": {
            "id": 1042,
            "code": "lunch-menu",
            "short_url": "https://siz.la/lunch-menu",
            "destination": "https://example.com/a/long/address",
            "title": null,
            "type": "direct",
            "created_at": "2026-11-14T09:30:00+00:00",
            "updated_at": "2026-11-14T09:30:00+00:00"
        }
    }
}

link.updated

JSON
{
    "id": "6f1d2c1e-8a47-4c35-9d0b-2a1c0f5e7b90",
    "event": "link.updated",
    "created_at": "2026-11-14T10:02:44+00:00",
    "data": {
        "link": {
            "id": 1042,
            "code": "lunch-menu",
            "short_url": "https://siz.la/lunch-menu",
            "destination": "https://example.com/a/long/address",
            "title": null,
            "type": "direct",
            "created_at": "2026-11-14T09:30:00+00:00",
            "updated_at": "2026-11-14T09:30:00+00:00"
        }
    }
}

link.clicked

JSON
{
    "id": "6f1d2c1e-8a47-4c35-9d0b-2a1c0f5e7b90",
    "event": "link.clicked",
    "created_at": "2026-11-14T10:02:44+00:00",
    "data": {
        "count": 1,
        "from": "2026-11-14 09:41:07",
        "to": "2026-11-14 09:41:07",
        "clicks": [
            {
                "id": 90211,
                "link_id": 1042,
                "code": "lunch-menu",
                "short_url": "https://siz.la/lunch-menu",
                "clicked_at": "2026-11-14T09:41:07+00:00",
                "country": "US",
                "city": "Austin",
                "referrer_host": "t.co",
                "ai_assistant": null,
                "browser": "Chrome",
                "os": "iOS",
                "device": "mobile",
                "is_new_visitor": true,
                "is_qr": false,
                "click_id": "3f9a6c1e5b7d40a28c91e0d4"
            }
        ]
    }
}

conversion.created

JSON
{
    "id": "6f1d2c1e-8a47-4c35-9d0b-2a1c0f5e7b90",
    "event": "conversion.created",
    "created_at": "2026-11-14T10:02:44+00:00",
    "data": {
        "conversion": {
            "id": 318,
            "link_id": 1042,
            "click_id": "3f9a6c1e5b7d40a28c91e0d4",
            "name": "purchase",
            "value": 49,
            "currency": "USD",
            "reference": "order-1042",
            "converted_at": "2026-11-14T10:02:44+00:00"
        }
    }
}

bio.signup

JSON
{
    "id": "6f1d2c1e-8a47-4c35-9d0b-2a1c0f5e7b90",
    "event": "bio.signup",
    "created_at": "2026-11-14T10:02:44+00:00",
    "data": {
        "signup": {
            "id": 77,
            "email": "[email protected]",
            "name": "Sam",
            "page_id": 9,
            "page_name": "Lunch menu",
            "page_url": "https://siz.la/lunch-menu",
            "block_id": "k3d9x2",
            "signed_up_at": "2026-11-14T09:52:10+00:00"
        }
    }
}

qr.scanned

JSON
{
    "id": "6f1d2c1e-8a47-4c35-9d0b-2a1c0f5e7b90",
    "event": "qr.scanned",
    "created_at": "2026-11-14T10:02:44+00:00",
    "data": {
        "count": 1,
        "from": "2026-11-14 09:44:51",
        "to": "2026-11-14 09:44:51",
        "clicks": [
            {
                "id": 90212,
                "is_qr": true,
                "clicked_at": "2026-11-14T09:44:51+00:00",
                "device": "mobile",
                "os": "Android",
                "browser": "Chrome",
                "city": "Leeds",
                "country": "GB",
                "click_id": "8c21d4f0a97e4b1c5e6a0b33",
                "link_id": 1042,
                "code": "lunch-menu",
                "short_url": "https://siz.la/lunch-menu",
                "referrer_host": "t.co",
                "ai_assistant": null,
                "is_new_visitor": true
            }
        ]
    }
}

Clicks are batched. All the clicks from the last minute for an endpoint go in one link.clicked message, up to 500 in a message. The scans of QR codes among them also go in one qr.scanned message, for an endpoint that asked for it. Clicks from bots are left out, and clicks older than an hour are not sent if an endpoint was off.

Zapier, Make, n8n, Slack and Mailchimp use these same messages. See integrations for how to connect them.

Check the signature

Anyone who learns your endpoint address can send it fake messages, so check every one. The signature is an HMAC with SHA-256:

  1. Read the t and v1 values from the X-Sizla-Signature header.
  2. Join t, a dot and the raw request body, exactly as it arrived. Do not parse and re-encode the JSON first.
  3. Sign that text with your endpoint's secret using HMAC-SHA256 and write the result as lowercase hex.
  4. Compare it with v1 using a constant-time comparison.
  5. Reject the message if t is more than five minutes old.
JavaScript
import crypto from "node:crypto";

// rawBody is the request body exactly as it arrived, before any JSON parsing.
export function isValid(rawBody, signatureHeader, secret) {
  const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const given = Buffer.from(parts.v1 ?? "");
  const wanted = Buffer.from(expected);
  return given.length === wanted.length && crypto.timingSafeEqual(given, wanted);
}
Python
import hashlib
import hmac
import time


def is_valid(raw_body: bytes, signature_header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False

    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))
PHP
function isValid(string $rawBody, string $signatureHeader, string $secret): bool
{
    parse_str(str_replace(',', '&', $signatureHeader), $parts);
    if (abs(time() - (int) ($parts['t'] ?? 0)) > 300) {
        return false;
    }

    $expected = hash_hmac('sha256', $parts['t'].'.'.$rawBody, $secret);

    return hash_equals($expected, $parts['v1'] ?? '');
}

Answering and retries

Answer with any 2xx status within 10 seconds. Redirects are not followed. Anything else counts as a failure, and the message is tried again after 30 seconds, 2 minutes, 10 minutes and 1 hour. An endpoint that fails 25 times in a row is paused, and you can turn it back on in the members area. The delivery log keeps 30 days, and from there you can send a message again.