Skip to documentation
Link 2 Link / Docs
Documentation home
Browse documentation

Developer reference

Webhooks

Receive minimal signed link events and build a receiver that tolerates retries.

Current product guide · Reviewed October 28, 2026

Create a receiver and subscription

  1. Prepare a public HTTPS endpoint on port 443 that you control. It must have a valid certificate and must not redirect.
  2. In Domains & integrations, choose a personal/workspace scope, name, endpoint URL and event types.
  3. Save the signing secret immediately in protected backend configuration. Do not use an API token as the webhook secret.
  4. Inspect recent delivery results in the dashboard. A successful HTTP response means your receiver accepted the request, not that its business process completed.

Up to five endpoints per account are supported by the current implementation. URLs with credentials, fragments, percent-encoded characters, unsupported ports or private/reserved destinations are rejected. Public DNS addresses are rechecked and pinned for each attempt. Localhost development receivers are not supported.

Events and payload

TypeWhen recorded
link.createdA link is created.
link.updatedA link update is submitted; do not assume every event implies a changed value.
link.deletedA link is permanently deleted.
link.clickedAn eligible GET redirect occurs; bots/repeats can contribute.
conversion.recordedA conversion submission is newly recorded.

json · example

{"id":"11111111-1111-4111-8111-111111111111","type":"link.created","occurred_at":"2026-10-27T12:00:00+00:00","data":{"link_id":42,"slug":"Guide2026"}}

Payloads deliberately exclude destinations, visitor identifiers, passwords and message content. If you need current link details, use an appropriately scoped API token after validation. A deleted link cannot be fetched as though it still exists.

Verify the exact bytes

Headers are X-Li2li-Id, X-Li2li-Timestamp and X-Li2li-Signature. The signature is sha256= followed by the hex HMAC-SHA256 of timestamp + "." + the exact raw request body, using the signing secret. Verify before parsing or acting. Do not reserialize JSON before computing the MAC.

Javascript example

// Node.js receiver helper; call with the unmodified raw body.
import { createHmac, timingSafeEqual } from "node:crypto";
export function verify(rawBody, timestamp, signature, secret, now = Date.now()) {
  if (!/^\d+$/.test(timestamp) || !/^sha256=[a-f0-9]{64}$/.test(signature)) return false;
  if (Math.abs(Math.floor(now / 1000) - Number(timestamp)) > 300) return false;
  const expected = createHmac("sha256", secret)
    .update(timestamp + ".").update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(signature.slice(7), "hex"));
}

Python example

# Pass raw request bytes and the exact header strings before parsing JSON.
import hashlib
import hmac
import re
import time

def verify(raw_body, timestamp, signature, secret, now=None):
    if not isinstance(raw_body, bytes):
        return False
    if not re.fullmatch(r"[0-9]{1,12}", timestamp or ""):
        return False
    if not re.fullmatch(r"sha256=[a-f0-9]{64}", signature or ""):
        return False
    if abs(int(time.time() if now is None else now) - int(timestamp)) > 300:
        return False
    expected = hmac.new(secret.encode("utf-8"),
        timestamp.encode("ascii") + b"." + raw_body, hashlib.sha256).digest()
    return hmac.compare_digest(expected, bytes.fromhex(signature[7:]))

Java example

// Save as WebhookVerifier.java. Use raw bytes, not a parsed/re-serialized body.
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.HexFormat;
import java.time.Instant;

public class WebhookVerifier {
    public static boolean verify(byte[] rawBody, String timestamp, String signature,
                                 String secret, long nowSeconds) throws Exception {
        if (rawBody == null || timestamp == null || signature == null || secret == null
            || !timestamp.matches("[0-9]{1,12}")
            || !signature.matches("sha256=[a-f0-9]{64}")) return false;
        if (Math.abs(nowSeconds - Long.parseLong(timestamp)) > 300) return false;
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        mac.update((timestamp + ".").getBytes(StandardCharsets.US_ASCII));
        byte[] expected = mac.doFinal(rawBody);
        return MessageDigest.isEqual(expected, HexFormat.of().parseHex(signature.substring(7)));
    }
    // Your handler calls verify(rawBytes, timestampHeader, signatureHeader,
    //     System.getenv("LI2LI_WEBHOOK_SECRET"), Instant.now().getEpochSecond()).
}

The five-minute timestamp tolerance above is receiver guidance, not a server-provided replay store. After verifying, parse the payload, confirm its id matches X-Li2li-Id, validate the type/schema, and atomically deduplicate by endpoint + event ID in durable storage. Return a 2xx for an already accepted duplicate. Persist acceptance before acknowledging; schedule slow business work separately. Set request/body limits and never log signing secrets or signatures.

For Python, supply os.environ["LI2LI_WEBHOOK_SECRET"] as secret; for Java, use System.getenv("LI2LI_WEBHOOK_SECRET"). These helpers use X-Li2li-Timestamp and X-Li2li-Signature exactly as received, UTC epoch seconds, a receiver-chosen ±300-second freshness window and UTF-8 secret bytes. Java nowSeconds and Python now are seconds (the Node helper uses milliseconds). Read X-Li2li-Id for durable deduplication after signature verification. Signature and freshness alone do not prevent a replay inside the window. Persist processed event IDs atomically with your side effect; respond with 2xx only after accepting the event. No helper starts a server or implements durable storage.

Delivery is retryable, not exactly once

Only 2xx is success. Redirects are not followed. Attempts have a 3-second connection and 10-second total timeout. Up to five attempts are made, with nominal waits of 1, 2, 4 and 8 minutes between attempts; scheduling and transient failures can extend those waits. A response body over the delivery limit can fail the attempt. Keep acknowledgments small.

Retries retain the event ID and payload but get a new timestamp/signature. A receiver may accept an event even if Li2.li misses its response, so duplicates are possible. Do not rely on strict ordering or infinite replay history. Recent delivery status shows attempts and safe error codes; it is not a full payload archive or manual replay console.

Still need a hand?

Use Help & support in your dashboard or support@li2.li. Share the action and a sanitized error, never a password, token or private reset link.