Signierter Postback

Conversions aus dem eigenen Server melden: was ein signierter Postback ist, welche Felder er braucht, und Beispiele.

Ein Postback ist eine Meldung deines Servers an colly: „Diese Bestellung gehört zu diesem Klick.“ Signiert heißt, dass dein Server jede Meldung mit seinem Secret versiegelt. colly erkennt daran, dass sie wirklich von dir stammt und unterwegs nicht verändert wurde. Das Secret selbst wird nie mitgeschickt.

Das ist die Lösung für eigene Backends und Tracker. Du brauchst dafür jemanden, der programmieren kann. Hast du einen fertigen Shop, ist eine andere Anbindung einfacher.

Diese Seite ist für Advertiser. Die Beschreibung steht unter Integration, Reiter Postback & API, Abschnitt Schnittstelle. Schlüssel von Creator-Konten gelten nicht für Postbacks und werden mit key_not_allowed abgelehnt. Die volle Technik mit Beispielen in Node.js und Python findest du in der Entwicklerdokumentation.

So läuft eine Meldung ab

1. 1

   Schritt 1: Schlüssel erstellen

   Erstelle unter API-Schlüssel einen Schlüssel und speichere Key-ID und Secret auf deinem Server. Siehe API-Schlüssel. Das Secret gehört nie in den Browser oder in Client-Code.

2. 2

   Schritt 2: Click-ID aufbewahren

   Die Ziel-URL deines Angebots enthält {click_id}. Speichere den Wert beim Besucher oder an der Bestellung, bis der Kauf abgeschlossen ist.

3. 3

   Schritt 3: Meldung bauen und signieren

   Dein Server baut die Nachricht, nimmt die aktuelle Zeit und berechnet daraus mit dem Secret die Signatur (HMAC-SHA256). Signiert wird der Zeitstempel, ein Punkt und der unveränderte Text der Nachricht.

4. 4

   Schritt 4: Senden und Antwort auswerten

   Dein Server sendet an /api/v1/postback. colly antwortet sofort mit dem Ergebnis, und die Meldung erscheint im Protokoll.

Eine Conversion melden

Beispiel. SECRET und CLICK_ID sind Platzhalter:

KEY="pk_…"; SECRET="sk_…"
TS=$(date +%s)
BODY='{"click_id":"CLICK_ID","event_id":"evt-1001","transaction_id":"order-1001","goal":"sale","amount":"49.90","currency":"EUR","status":"pending"}'
SIG="v1=$(printf '%s' "$TS.$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')"

curl -sS -X POST "https://joincolly.com/api/v1/postback" \
  -H "Content-Type: application/json" \
  -H "X-Colly-Key: $KEY" \
  -H "X-Colly-Timestamp: $TS" \
  -H "X-Colly-Signature: $SIG" \
  --data-raw "$BODY"

Antworten, die du bekommen kannst:

200 {"status":"accepted","conversion_id":"cm…","conversion_status":"pending"}
200 {"status":"duplicate","conversion_id":"cm…"}
422 {"status":"rejected","error":"attribution_window_expired"}
401 {"status":"rejected","error":"invalid_signature"}

Bei accepted entsteht die Conversion mit Status Ausstehend und der Creator wird benachrichtigt, außer die Meldung war mit test als Test gesendet. Sendest du approved, wird sie sofort Freigegeben. Ist das Risiko der Conversion hoch, bleibt sie trotzdem Ausstehend, und die Antwort enthält risk_review. Du entscheidest dann selbst unter Conversions.

Den Status ändern

Mit /api/v1/conversions/status gibst du eine Conversion frei, lehnst sie ab oder stornierst sie. Die Signatur funktioniert genauso.

Andere Wechsel beantwortet colly mit 409 transition_not_allowed. Abgelehnte und stornierte Conversions lassen sich nicht reaktivieren. Hat die Conversion den Zielstatus schon, lautet die Antwort unchanged. Der Text in reason (höchstens 500 Zeichen) ist für den Creator sichtbar. Der Creator wird über die Statusänderung benachrichtigt.

BODY='{"event_id":"evt-1002","transaction_id":"order-1001","goal":"sale","status":"reversed","reason":"refund"}'
# Signatur und Header wie oben / signature and headers as above
curl -sS -X POST "https://joincolly.com/api/v1/conversions/status" … --data-raw "$BODY"

Was du dir merken solltest

• Jede Signatur gilt nur einmal. Dieselbe Signatur nochmal ergibt replay_detected. Signiere jeden Versuch neu.
• Der Zeitstempel darf nur wenig abweichen. Standard sind 5 Minuten, das Netzwerk kann das einstellen. Sonst lautet der Fehler timestamp_out_of_range. Prüfe dann die Serverzeit.
• Bei `429` und `5xx` später erneut senden, mit derselben event_id und neuer Signatur. So wird nichts doppelt gebucht. Die Grenze liegt bei 600 Meldungen je Minute und Schlüssel.
• Nach einer fachlichen Ablehnung eine neue `event_id` nehmen. Dieselbe abgelehnte event_id liefert immer wieder dieselbe Ablehnung.
• Nur über HTTPS und vom Server senden. Die Nachricht darf höchstens 16 KB groß sein.

Antworten und Fehlercodes

Die Seite listet alle Codes mit Erklärung. Eine nach Situation sortierte Übersicht findest du unter Protokoll.

Zum Ausprobieren, ohne selbst zu signieren, gibt es die Testkonsole.

• TestkonsoleEinen signierten Postback aus der App senden.
• EntwicklerdokumentationBeispiele in Node.js und Python.
• API-SchlüsselKey-ID und Secret erstellen.