Webhooks

Webhooks schicken Ereignisse als JSON-POST-Anfragen an Ihren Endpunkt — ohne Abfragen im Takt. Registrieren Sie Endpunkte im Dashboard (Einstellungen → Webhooks) oder per POST /v1/webhooks; das Signaturgeheimnis wird bei der Erstellung einmalig angezeigt.

Ereignisse

| Ereignis | Wird ausgelöst, wenn | Verfügbar für | |---|---|---| | link.created / link.updated / link.deleted | Ein Link sich ändert — über Dashboard, API oder Massenimport | Workspace- und Partner-Endpunkte | | domain.pending_ssl | DNS geprüft, Zertifikat wird ausgestellt | Workspace und Partner | | domain.activated | Die Domain liefert Traffic aus | Workspace und Partner | | domain.error | Die Bereitstellung ist fehlgeschlagen; Details enthalten | Workspace und Partner | | click.threshold | 80 % / 100 % des monatlichen Limits erfasster Klicks | Workspace und Partner | | conversion.created | Eine Conversion wurde erfasst: eine Bestellung, eine Anmeldung oder ein eigenes Ziel, einem Klick zugerechnet | Workspace und Partner | | workspace.subscribed | Ein Kunde hat die erste Rechnung eines Abos bezahlt | nur Partner | | workspace.past_due | Eine Kundenzahlung ist fehlgeschlagen | nur Partner | | workspace.suspended | Ein Kunde wurde gesperrt (Mahnlauf oder manuell) | nur Partner | | payment.succeeded | Eine Kundenzahlung ist verrechnet, mit Gebührenaufschlüsselung | nur Partner | | payment.refunded | Eine Zahlung wurde erstattet | nur Partner |

Die Zustellung

POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-LinkProfit-Event: link.created
X-LinkProfit-Delivery: dlv_8Yq2…
X-LinkProfit-Signature: t=1755081600,v1=5f8a2c…

{
  "id": "dlv_8Yq2…",
  "type": "link.created",
  "created_at": "2026-08-13T10:00:00.000Z",
  "data": { "id": "lnk_…", "domain": "go.your-brand.com", "slug": "x7f2q1z", "url": "https://example.com" }
}

Antworten Sie innerhalb von 10 Sekunden mit einem beliebigen 2xx. Alles andere — auch ein Timeout — gilt als Fehlschlag und plant eine Wiederholung ein. Zustellungen können in abweichender Reihenfolge und selten auch doppelt eintreffen: Entdoppeln Sie über die id.

Die Signatur prüfen

Die Signatur ist HMAC-SHA256 über `${t}.${rawBody}` mit dem Geheimnis Ihres Endpunkts, hex-kodiert. Prüfen Sie immer gegen den rohen Anfragerumpf, vor jedem JSON-Parsen, und weisen Sie Zeitstempel zurück, die älter als 5 Minuten sind.

import { createHmac, timingSafeEqual } from "node:crypto";

function verifySignature(secret, rawBody, header, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    header.split(",").map((piece) => piece.split("=", 2)),
  );
  if (!parts.t || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSeconds) return false;

  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1);
  return a.length === b.length && timingSafeEqual(a, b);
}

import hashlib
import hmac
import time


def verify_signature(secret: str, raw_body: bytes, header: str, tolerance: int = 300) -> bool:
    parts = dict(piece.split("=", 1) for piece in header.split(",") if "=" in piece)
    timestamp, signature = parts.get("t"), parts.get("v1")
    if not timestamp or not signature:
        return False
    if abs(time.time() - int(timestamp)) > tolerance:
        return False

    expected = hmac.new(
        secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Wiederholungen und der Fehlerzustand

Der erste Versuch erfolgt sofort. Fehlschläge werden nach festem Plan wiederholt: 1 Min. → 5 Min. → 30 Min. → 2 Std. → 12 Std. Nach der fünften Wiederholung wird der Endpunkt als failing markiert, erhält keine neuen Ereignisse mehr, und der Inhaber bekommt eine E-Mail.

Reparieren Sie den Endpunkt und aktivieren Sie ihn dann im Dashboard oder mit PATCH /v1/webhooks/{id} und {"status": "active"} wieder. Verpasste Ereignisse werden nicht automatisch nachgeliefert — das Zustellprotokoll (GET /v1/webhooks/{id}/deliveries oder das Dashboard) zeigt jede Nutzlast, sodass Sie abgleichen können.

Eine erfolgreiche Zustellung setzt die Fehlerserie zurück.

Testen

Der Button Test senden (oder POST /v1/webhooks/{id}/test) stellt ein echtes, signiertes Ereignis mit "data": { "test": true } über dieselbe Verarbeitungskette zu wie Produktionsereignisse — das Zustellprotokoll zeigt die Antwort Ihres Endpunkts.