Universeller Webhook

Jedes System anbinden, das HTTP-Anfragen senden kann: Felder zuordnen, mit einem Testlauf prüfen, Nachrichten absichern.

Der universelle Webhook ist für alles, wofür es keine fertige Anbindung gibt, etwa Shopware Cloud, Magento, PrestaShop, eigene Skripte oder Automatisierungen. Dein System schickt eine Nachricht an eine Adresse bei colly. Du sagst colly, in welchem Feld dieser Nachricht was steht.

Diese Seite ist für Advertiser. Du findest alles unter Integration, Reiter Universeller Webhook. Anlegen und ändern dürfen im Team nur Eigentümer:in und Admin.

1234

1. 1Markierung 1: Kopieren legt die Webhook-URL in die Zwischenablage. An diese Adresse sendet dein System per POST.
2. 2Markierung 2: Testlauf mit Beispielnachricht klappt das Testfeld auf. Siehe Testlauf.
3. 3Markierung 3: Einstellungen klappt Absicherung und Zuordnung dieser Anbindung auf. Dort kannst du sie auch über Aktiv ausschalten oder mit Entfernen löschen.
4. 4Markierung 4: Webhook verbinden klappt das Formular für eine weitere Anbindung auf. Jede Anbindung hat eine eigene Adresse und eigene Zuordnung.

1234

Einrichtung Schritt für Schritt

1. 1

   Schritt 1: Schlüssel erzeugen und Absicherung wählen

   Öffne Webhook verbinden, vergib eine Bezeichnung und wähle bei Bedarf ein Ziel. Klicke auf Schlüssel erzeugen und kopiere den Wert sofort.

   12345

   1. 1Markierung 1: Schlüssel erzeugen füllt das Feld darüber mit einem Zufallswert. Das passiert nur in deinem Browser und speichert noch nichts. Kopiere ihn vor dem Speichern, danach wird er nie mehr angezeigt.
   2. 2Markierung 2: Verfahren: Geheimer Schlüssel im Header oder HMAC-SHA256-Signatur. Bei HMAC erscheinen die zwei Felder darunter.
   3. 3Markierung 3: Name des Headers: Hier erwartet colly den Schlüssel oder die Signatur. Standard ist x-colly-token.
   4. 4Markierung 4: Kodierung der Signatur: Hex oder Base64, je nachdem, was dein System sendet.
   5. 5Markierung 5: Vorsatz der Signatur: Optional ein fester Text vor der Signatur, zum Beispiel sha256=.

   12345

2. 2

   Schritt 2: Felder zuordnen

   Trage bei Felder deiner Nachricht den Pfad jedes Werts ein. Die Punktnotation führt durch die Nachricht: order.total meint das Feld total in order, items.0.sku das Feld sku im ersten Listeneintrag. Pfade dürfen Buchstaben, Ziffern, _ und - enthalten.

   1234

   1. 1Markierung 1: Bestell-ID ist Pflicht und muss je Bestellung eindeutig sein. Daran erkennt colly Wiederholungen.
   2. 2Markierung 2: Click-ID oder Gutscheincode: Mindestens eines von beiden musst du zuordnen. Sonst erscheint: Bitte Click-ID oder Gutscheincode zuordnen.
   3. 3Markierung 3: Einheit des Betrags: Euro (49.90) oder Cent (4990). Bei Euro geht auch ein Komma als Dezimaltrennzeichen, aber kein Tausendertrenner.
   4. 4Markierung 4: Ereignis-ID ist optional. Ohne sie bildet colly die ID aus der Bestell-ID.

   1234

3. 3

   Schritt 3: Festlegen, was als gebucht gilt

   Siehe den nächsten Abschnitt. Klicke dann auf Webhook verbinden. Es erscheint Anbindung angelegt, und die Webhook-URL steht bereit.

   12

   1. 1Markierung 1: Die Bestätigung Anbindung angelegt verschwindet nach einigen Sekunden.
   2. 2Markierung 2: Kopieren legt die Webhook-URL in die Zwischenablage.

   12

4. 4

   Schritt 4: Click-ID bis zur Zahlung aufbewahren

   Setze beim Angebot die Ziel-URL mit {click_id}, und speichere die Click-ID in deinem System bis zur Zahlung.

5. 5

   Schritt 5: Nachrichten senden lassen

   Lass dein System bei jeder bezahlten Bestellung per POST an die Webhook-URL senden, als JSON oder Formular (application/x-www-form-urlencoded), mit dem Schlüssel im eingestellten Header. Beim geheimen Schlüssel ist auch die Form Bearer … erlaubt.

6. 6

   Schritt 6: Mit dem Testlauf prüfen

   Füge eine Beispielnachricht in den Testlauf ein und prüfe die erkannten Werte. Danach zeigt das Protokoll, was wirklich ankommt. Die event_id beginnt dort mit custom-.

Beispiel für eine Nachricht, die zur Zuordnung oben passt:

POST https://joincolly.com/api/integrations/hooks/…
Content-Type: application/json
x-colly-token: SECRET_KEY

{
  "order": {
    "id": "1001",
    "total": "49.90",
    "currency": "EUR",
    "click_id": "CLICK_ID",
    "coupon": "ANNA10"
  },
  "status": "paid"
}

Was als gebucht gilt

123

1. 1Markierung 1: Feld: Pfad zu dem Wert, der sagt, was passiert ist. Bleibt es leer, gilt jede Nachricht als bezahlte Bestellung.
2. 2Markierung 2: Werte für „bezahlt“: mit Komma getrennt. Sie erzeugen eine Conversion. Wenn du ein Feld setzt, ist mindestens ein Wert Pflicht.
3. 3Markierung 3: Werte für „erstattet“: mit Komma getrennt. Sie stornieren die Conversion.

123

Jede Nachricht läuft durch dieselben Prüfungen wie ein Postback: Zuordnung, Zeitfenster, Ziel, Währung und Limits. Bei prozentualer Provision ist ein Betrag Pflicht, sonst lautet der Fehler amount_required.

Der Testlauf

Der Testlauf zeigt, wie colly eine Nachricht versteht. Es wird nichts gebucht. Geprüft wird die zuletzt gespeicherte Zuordnung. Speichere Änderungen also vorher.

123

1. 1Markierung 1: Beispielnachricht (JSON): Füge hier eine echte Beispielnachricht deines Systems ein. Ist sie kein gültiges JSON, erscheint: Bitte eine gültige JSON-Nachricht einfügen.
2. 2Markierung 2: Testlauf starten wertet die Nachricht aus. Die Daten ändern sich dabei nicht.
3. 3Markierung 3: Das Ergebnis mit den erkannten Werten. Grün heißt: Die Nachricht würde etwas auslösen.

123

Signatur und Schlüssel

• Passt Schlüssel oder Signatur nicht, antwortet colly mit 401, und das Protokoll zeigt Abgelehnt mit invalid_signature.
• Der Schlüssel wird verschlüsselt gespeichert und nicht mehr angezeigt. In den Einstellungen steht dann: Hinterlegt (verschlüsselt). Leer lassen, um ihn beizubehalten. Einen neuen Wert kannst du dort jederzeit eintragen.
• Fehlt der Schlüssel, lautet der Status Ausstehend und colly lehnt jede Nachricht mit not_configured ab.

123

1. 1Markierung 1: Aktiv mit Schlüssel. Zuletzt: nennt die letzte Nachricht.
2. 2Markierung 2: Ausstehend: Es fehlt der Schlüssel.
3. 3Markierung 3: Deaktiviert: Die Adresse antwortet mit 404. Der gespeicherte Schlüssel bleibt erhalten.

123

Wiederholungen und abgelehnte Nachrichten

Schickt dein System dieselbe Bestellung noch einmal, bucht colly nicht doppelt. Das gilt auch umgekehrt: Wurde eine Nachricht abgelehnt und du behebst die Ursache, liefert dieselbe Ereignis-ID weiter dieselbe Ablehnung.

colly antwortet auf fachliche Ablehnungen mit 200, damit dein System nicht endlos wiederholt. Den Grund siehst du im Protokoll und in der Antwort. Andere Antworten: 400 ungültige Nachricht, 401 Signaturfehler, 404 entfernte oder inaktive Anbindung, 429 zu viele Nachrichten (Grenze: 600 je Minute), 500 interner Fehler. Wiederhole bei 429 und 500 später.

Häufige Probleme

• Zapier, Make und n8nDen Webhook ohne Programmieren füttern.
• ProtokollSehen, was wirklich ankommt.
• Signierter PostbackDie Alternative für eigene Entwicklung.