Verkäufe und eigene Daten an LinkHarbor senden

LinkHarbor nimmt Daten auch von außen an. Für zwei Fälle gibt es eigene Endpunkte mit eigenen Secrets – du brauchst dafür keinen API-Key: Sale-Callbacks melden Verkäufe aus deinem Shop, damit du in der Statistik siehst, welcher Link Umsatz gebracht hat. Die Integration „Custom (API)“ bringt Live-Daten aus eigenen Tools als Widget auf deine Page und kann Push-Nachrichten auslösen.

#Sale-Callbacks: Verkäufe zuordnen

Wie Klick-ID (lt_click_id), Zuordnung und Auswertung zusammenhängen, erklärt Conversions und Verkäufe zuordnen; hier stehen alle Felder und Antworten für Entwickler. Kurz: LinkHarbor hängt beim Weiterleiten eines gezählten Klicks auf ein http- oder https-Ziel den Parameter lt_click_id an, dein Shop merkt ihn sich und schickt ihn nach dem Kauf zurück.

Callback-Secret anlegen

1. Öffne „Callback & API“
2. Klicke in der Karte „Callback-Secrets“ auf „+ Neuen Secret erstellen“
3. Vergib optional einen Namen, zum Beispiel „Shop-Callback“, und klicke auf „Secret erstellen“
4. Kopiere das Secret sofort – es wird nur einmal angezeigt

Wer

Eigentümer und Admins, ab Creator Pro. In Creator Free steht dort „Callback-Secrets sind ab Creator Pro verfügbar.“

Anzahl

Bis zu 5 Secrets pro Workspace, etwa eines pro Shop.

„Bearbeiten“

Name ändern und den Status auf „Aktiv“ oder „Inaktiv“ setzen. Mit einem inaktiven Secret lehnt die API Callbacks ab.

„↺ Rotieren“

Erzeugt ein neues Secret; das alte wird sofort ungültig.

„Letzter Callback:“

Zeigt, wann das Secret zuletzt erfolgreich genutzt wurde.

Callback senden

curl -X POST https://dock.at-harbor.com/v1/callbacks/sale \
  -H "Content-Type: application/json" \
  -H "X-Callback-Secret: $LH_CALLBACK_SECRET" \
  -d '{
    "click_id": "3f1c2a9e-8d4b-4a51-9f0e-6b7c1d2e3f40",
    "order_id": "A-10023",
    "amount": "49.90",
    "currency": "EUR",
    "occurred_at": "2026-11-01T10:15:00Z"
  }'
# → {"ok":true,"conversion_id":123}

Optionale Signatur

Zusätzlich zum Secret kannst du den Header X-Callback-Signature senden. Er enthält sha256= und die HMAC-SHA256-Signatur des rohen Bodys in Hex. Als Schlüssel dient nicht das Secret selbst, sondern sein SHA-256-Hash in binärer Form. Schickst du den Header, muss er stimmen – sonst wird der Callback abgelehnt.

<?php
$body = json_encode($payload);
$key  = hash('sha256', getenv('LH_CALLBACK_SECRET'), true); // binärer Hash des Secrets
$sig  = 'sha256=' . hash_hmac('sha256', $body, $key);
// Header: X-Callback-Secret und X-Callback-Signature: $sig, Body: $body

Wo du die Verkäufe siehst

Gemeldete Verkäufe erscheinen als Conversions in der Statistik, siehe Conversions und Verkäufe zuordnen. Über die API liest du sie mit read:stats unter /v1/stats/…/conversions/breakdown.

#Custom (API): eigene Live-Daten

Mit der Integration „Custom (API)“ schickt jedes Programm, das HTTP-Anfragen senden kann – ein Spielserver-Plugin, ein Bot, ein Cron-Skript –, Daten an LinkHarbor. Daraus wird ein Live-Widget auf deiner Page, und über Push-Regeln können deine Follower benachrichtigt werden.

Verbinden

1. Öffne im Workspace „Integrationen“
2. Wähle „Custom (API)“ und gib einen Namen ein
3. Nach dem Verbinden zeigt der Dialog „Ingest-URL“ und „Secret“ (mit „Secret anzeigen“)
4. Hinterlege beides in deinem Tool

Integrationen gibt es ab Creator Pro. Ingest-URL und Secret sehen nur Eigentümer und Admins, auch später im Detailbereich der Integration. Trennen und neu verbinden erzeugt ein neues Secret. Wie du Integrationen allgemein verbindest, steht unter Integration verbinden.

Daten senden

curl -X POST "$INGEST_URL" \
  -H "Authorization: Bearer $INGEST_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "player.joined",
    "event_id": "join-2026-11-01T20:01:02Z-steve",
    "data": { "player": "Steve" },
    "state": {
      "type": "game_server",
      "name": "Survival SMP",
      "online": true,
      "players_online": 3,
      "players_max": 20
    }
  }'
# → {"ok":true,"event_id":4711,"duplicate":false,"event_type":"player.joined"}

event

Freier Event-Name, zum Beispiel player.joined. Er wird in Kleinbuchstaben umgewandelt und ist der Name, auf den Push-Regeln reagieren. Ohne event heißt das Event state.updated.

event_id

Optionaler Schlüssel gegen doppelte Verarbeitung. Wird dieselbe event_id erneut geschickt, antwortet LinkHarbor mit duplicate: true und tut nichts.

data

Werte für die Platzhalter in Push-Texten, zum Beispiel {player}. Bis zu 40 Schlüssel, nur einfache Werte.

state

Der komplette Zustand des Widgets. Er ersetzt den bisherigen vollständig. type ist game_server (Spielserver-Karte) oder status (Status-Karte).

Statt Authorization: Bearer kannst du das Secret auch im Header X-LinkHarbor-Secret senden. Pro IP-Adresse sind 120 Aufrufe pro Minute erlaubt. Optional signierst du den Body: Der Header X-LinkHarbor-Signature enthält sha256= und die HMAC-SHA256-Signatur des rohen Bodys mit dem Secret als Schlüssel. Schickst du ihn, muss er stimmen.