Rebrandly Webhooks: Technischer Implementierungsleitfaden

Marketing- und Entwicklungsteams befassen sich mit isolierten Klickdaten. Berichte kommen Stunden zu spät an. Manuelle Exporte führen zu Fehlern. Entscheidungen werden auf der Grundlage veralteter Informationen getroffen.

Rebrandly-Webhooks liefern Klickereignisdaten innerhalb von 10 Sekunden nach jeder Interaktion an Ihre Systeme. Analytics-Aktualisierung in Echtzeit. Automatisierungen werden ausgelöst, wenn die Benutzerabsicht aktiv ist. Teams sehen den gesamten Kampagnenkontext, ohne sich bei mehreren Plattformen anmelden zu müssen.

Im Vergleich zu Umfragen: Anstatt wiederholt nach neuen Klicks zu suchen, liefern Webhooks Ereignisse, sobald sie eintreten; weniger API-Aufrufe, keine Verzögerungen bei der Abfrage, geringere Infrastrukturkosten.

Im Vergleich zu Batch-Exporten: Manuelle Exporte bedeuten, dass Sie daran denken müssen, Daten abzurufen, Dateiformate zu konvertieren und auf Zielsysteme hochzuladen. Webhooks automatisieren diesen Arbeitsablauf und reduzieren die manuelle Dateneingabe um 95%.

Dieser Leitfaden behandelt Implementierungs-, Sicherheits- und Integrationsmuster für Entwickler, die automatisierte Workflows mit der Webhook-Infrastruktur von Rebrandly erstellen.

Die Webhook-Nutzlast

Jedes Mal, wenn jemand auf Ihren Markenlink klickt, sendet Rebrandly einen HTTP-POST mit dieser JSON-Nutzlast an Ihren Endpunkt:

{
  "data": [
    {
      "timestamp": "2025-10-25T02:36:47.132Z",
      "client": {
        "agent": {
          "browser": {
            "name": "chrome-mobile",
            "version": "121.0.0.0"
          },
          "os": {
            "name": "android",
            "version": "android-10"
          },
          "device": {
            "name": "smartphone"
          }
        },
        "geo": {
          "country": "US",
          "region": "CA",
          "city": "San Francisco"
        }
      },
      "route": {
        "id": "12345abcde",
        "slashtag": "product-launch",
        "createdAt": "2023-08-31T04:13:48.385",
        "domain": {
          "id": "8f104cc5b6ee4a4ba7897b06ac2ddcfb",
          "raw": "brand.link",
          "zone": "link.brand"
        },
        "destination": {
          "raw": "https://example.com/landing-page",
          "protocol": "https",
          "hostname": "example.com",
          "path": "/landing-page"
        }
      }
    }
  ],
  "key": "userId_32f5164718384fcda6503f550295885e-configId_db2a7cdeb91f4a2b9"
}

‍

Header anfordern:

• Inhaltstyp: Anwendung/json
• X-Rebrandly-Secret: your_secret_key (zur Authentifizierung)

Was ist in der Nutzlast:

• timestamp — ISO 8601 UTC-Zeitstempel. Verwenden Sie dies, um Ereignisse zu sortieren, wenn sie nicht in der richtigen Reihenfolge eintreffen.
• client.agent - Browser, Betriebssystem, Gerätetyp. Gut für Analysen und Bot-Erkennung.
• client.geo - Land, Region, Stadt. Wird für geografische Analysen oder Lokalisierungen verwendet.
• client.location — Geografische Daten mit Ländercodes im ISO 3166-1 A-2-Format (z. B. „uns“, „es“). Regionscodes verwenden das ISO 3166-1-Alpha-2-Format. Der Standort wird durch die IP-Adresse bestimmt.
• Route — Link-ID, Slashtag (die hintere Hälfte Ihres Kurzlinks), Domain, Ziel-URL. Verbindet Klicks mit bestimmten Kampagnen.
• key - Eindeutiger Bezeichner im Format `RB-Clicks-Stream-1-YYYY-MM-DD-HH-MM-SS- (GUID) `. Dies ist für Rebrandly nützlicher, um den Klick bei Bedarf schnell zu finden.

Grundlegende Implementierung

Hier ist ein minimaler Webhook-Endpunkt, der das Geheimnis validiert und Ereignisse speichert:

# Python/Flask example
from flask import Flask, request, jsonify
import os

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook_handler():
    # 1. Validate the secret key
    expected_secret = os.environ.get('apikey')
    received_secret = request.headers.get('apikey')
    
    if expected_secret != received_secret:
        return jsonify({'error': 'Unauthorized'}), 401
    
    # 2. Get the payload
    event_data = request.get_json()
    
    # 3. Process it (store, forward, trigger workflows)
    for event in event_data['data']:
        print(f"Click at {event['timestamp']}")
        print(f"Link: {event['route']['slashtag']}")
        print(f"Location: {event['client']['geo']['city']}")
        # Save to database, call other APIs, etc.
    
    # 4. Return success quickly (within 30 seconds)
    return jsonify({'status': 'received'}), 200

if __name__ == '__main__':
    app.run(port=5000)

// Node.js/Express example
const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
    // 1. Validate the secret key
    const expectedSecret = process.env.REBRANDLY_SECRET_KEY;
    const receivedSecret = req.headers['apikey'];
    
    if (expectedSecret !== receivedSecret) {
        return res.status(401).json({ error: 'Unauthorized' });
    }
    
    // 2. Get the payload
    const eventData = req.body;
    
    // 3. Process it
    eventData.data.forEach(event => {
        console.log(`Click at ${event.timestamp}`);
        console.log(`Link: ${event.route.slashtag}`);
        console.log(`Location: ${event.client.geo.city}`);
        // Save to database, call other APIs, etc.
    });
    
    // 4. Return success quickly
    res.status(200).json({ status: 'received' });
});

app.listen(5000, () => {
    console.log('Webhook listener running on port 5000');
});

Ihre Endpunktanforderungen:

• HTTP-POST-Anfragen akzeptieren
• Validieren Sie den Apikey-Header
• Reagieren Sie innerhalb von 5 Sekunden (geben Sie bei Erfolg 200-299 Statuscodes zurück)
• Per HTTPS erreichbar sein
• Umgang mit JSON-Payloads

Kritische Zuverlässigkeitsinformationen

Fehlgeschlagene Lieferungen werden nicht erneut versucht. Jedes Ereignis wird einmal gesendet. Wenn Ihr Endpunkt ausgefallen ist oder einen Fehler zurückgibt, ist dieses Ereignis vorbei.

Ereignisse können nicht in der richtigen Reihenfolge eintreffen. Netzwerkbedingungen können dazu führen, dass spätere Klicks vor früheren eintreffen. Verwenden Sie das Zeitstempelfeld, um Ereignisse korrekt zu sortieren.

Design für Zuverlässigkeit:

• Ereignisse schnell annehmen, asynchron verarbeiten
• Datenbankoperationen idempotent machen (sicher wiederholbar)
• Integrieren Sie Redundanz in Ihren Endpunkt
• Überwachen Sie verpasste Ereignisse
• Überprüfen Sie in kritischen Anwendungsfällen die Webhook-Daten mit regelmäßigen API-Abfragen

Asynchrones Verarbeitungsmuster

Verarbeiten Sie Ereignisse in Ihrem Webhook-Handler nicht synchron. Akzeptieren Sie das Ereignis, stellen Sie es in die Warteschlange, geben Sie sofort den Erfolg zurück und verarbeiten Sie es dann im Hintergrund:

# Python with queue-based processing
from flask import Flask, request, jsonify
import queue
import threading

app = Flask(__name__)
event_queue = queue.Queue()

@app.route('/webhook', methods=['POST'])
def webhook_handler():
    # Validate secret key
    if not validate_webhook(request):
        return jsonify({'error': 'Unauthorized'}), 401
    
    # Queue event immediately, don't process synchronously
    event_data = request.get_json()
    event_queue.put(event_data)
    
    # Return success before processing
    return jsonify({'status': 'received'}), 200

def process_events():
    while True:
        event = event_queue.get()
        # Process event: save to database, call APIs, etc.
        handle_event(event)
        event_queue.task_done()

# Start background processor
processor = threading.Thread(target=process_events, daemon=True)
processor.start()

Dadurch bleibt Ihr Endpunkt schnell (reagiert in weniger als einer Sekunde), wodurch das Timeout-Risiko reduziert wird, während Ereignisse dennoch gründlich verarbeitet werden.

Bewährte Sicherheitsmethoden

Bestätigen Sie immer den geheimen Schlüssel. Wenn du im Rebrandly-Dashboard einen Webhook erstellst, generieren wir ein zufälliges Geheimnis. Wir senden dies im Apikey-Header. Überprüfe es bei jeder Anfrage.

Geheimer Schlüssel: Ihr geheimer Schlüssel ist eine Standard-UUID (128-Bit-Identifier) im Format von 8-4-4-4-12 Hexadezimalzeichen (z. B. 550e8400-e29b-41d4-a716-446655440000). Dies folgt dem UUID v4-Standard.

Wenn das Geheimnis rotiert wird und ein Benutzer die UUID in einem externen System verwendet, muss er sie aktualisieren. Beachten Sie, dass dieser Schlüssel nicht erforderlich ist, um Webhooks aufzurufen.

Geheimnisse richtig aufbewahren:

• Verwenden Sie Umgebungsvariablen oder einen Secrets Manager
• Übergeben Sie niemals Geheimnisse an die Versionskontrolle
• Geheimnisse regelmäßig wechseln

Behandeln Sie Webhooks wie jede externe API:

• Validieren Sie alle Daten, bevor Sie sie verwenden
• Bereinigen Sie Eingaben vor Datenbankoperationen
• Ratenlimit zur Verhinderung von Missbrauch
• Authentifizierungsfehler für die Sicherheitsüberwachung protokollieren

Leistung und Grenzen

Geschwindigkeit der Lieferung: Ereignisse treffen in der Regel innerhalb weniger Sekunden bis ein paar Minuten nach dem Klick ein. Das Batching wird direkt von AWS verwaltet, wenn wir die Klicks speichern. Je nach Volumen werden Batches oder einzelne Klicks ausgelöst.

Erfolgsquote: Wir halten an einer Erfolgsrate von 99,9% fest (Hinweis: Bei dieser Messung sind Ausfälle an Kundenendpunkten nicht berücksichtigt — nur erfolgreiche Sendungen von Rebrandly).

Keine Ratenbegrenzungen für Veranstaltungen: Ihr Endpunkt empfängt Ereignisse so schnell, wie Leute auf Ihre Links klicken — von gelegentlichem Traffic bis hin zu starken Ausbrüchen während großer Kampagnen. Derzeit sind keine Limits festgelegt. Ereignisse werden auf unserer Seite in die Warteschlange gestellt, sodass Ihr Endpunkt sie so schnell empfängt, wie er sie verarbeiten kann.

Planbasierte Webhook-Limits (dies sind Konfigurationslimits, keine Event-Limits):

• Professionell: 1 Webhook-Endpunkt
• Wachstum: 5 Webhook-Endpunkte
• Unternehmen: maximal 100 Webhook-Endpunkte

Wenn Sie das Webhook-Limit erreichen, können Sie alte Webhooks löschen, die Sie nicht benötigen. Es gibt Warnungen, wenn Sie sich dem Limit nähern.

Gestalten Sie Ihren Webhook-Listener so, dass er Verkehrsspitzen bewältigt. Verwenden Sie Load Balancing, Auto-Scaling und Connection Pooling für Kampagnen mit hohem Traffic.

Testen Sie Ihren Webhook

1. Richten Sie einen Testendpunkt ein

Verwenden Sie einen Dienst wie webhook.site und erstellen Sie eine öffentliche URL für lokale Tests.

2. Erstellen Sie den Webhook in Rebrandly

Gehe zu Kontoeinstellungen > Webhooks:

• Name: „Webhook testen“
• URL: Ihre Testendpunkt-URL
• Secret: Kopieren Sie das generierte Geheimnis in Ihre Umgebungsvariablen
• Workspace: Wähle aus, welche Workspace-Links Ereignisse auslösen

3. Senden Sie eine Testveranstaltung

Klicken Sie im Rebrandly-Dashboard auf „Testevent senden“. Überprüfe deine Endpoint-Logs, um Folgendes zu verifizieren:

• Die Veranstaltung kommt
• Geheime Validierungsausweise
• Payload wird korrekt analysiert

Testereignisformat: Testereignisse verwenden synthetische Daten, entsprechen jedoch der exakten Struktur der Produktionsnutzlasten. Es werden nicht alle Parameter ausgefüllt — die Testereignisse dienen zur Überprüfung der Konnektivität und Authentifizierung, nicht zur Darstellung der tatsächlichen Klickdaten.

4. Löse einen echten Klick aus

Klicken Sie auf einen Ihrer Markenlinks. Innerhalb von 10 Sekunden sollten Sie einen Webhook mit echten Klickdaten erhalten.

5. Fehlerszenarien testen

• Gib einen 500-Fehler von deinem Endpunkt zurück (das Ereignis wird nicht wiederholt)
• Es dauert länger als 30 Sekunden, um zu antworten (Zeitlimit für Anfragen überschritten)
• Ungültige Statuscodes zurückgeben (Webhook-Lieferung schlägt fehl)

Beispiele für Integrationen

Klicks an BigQuery streamen

from google.cloud import bigquery
from flask import Flask, request, jsonify

app = Flask(__name__)
client = bigquery.Client()
table_id = "project.dataset.clicks"

@app.route('/webhook', methods=['POST'])
def webhook_handler():
    if not validate_webhook(request):
        return jsonify({'error': 'Unauthorized'}), 401
    
    event_data = request.get_json()
    rows = []
    
    for event in event_data['data']:
        rows.append({
            'timestamp': event['timestamp'],
            'slashtag': event['route']['slashtag'],
            'country': event['client']['geo']['country'],
            'city': event['client']['geo']['city'],
            'device': event['client']['agent']['device']['name'],
            'destination': event['route']['destination']['raw']
        })
    
    # Insert rows into BigQuery
    errors = client.insert_rows_json(table_id, rows)
    
    if errors:
        print(f"Errors: {errors}")
        return jsonify({'status': 'error'}), 500
    
    return jsonify({'status': 'received'}), 200

HubSpot-Workflow auslösen

const express = require('express');
const axios = require('axios');

app.post('/webhook', async (req, res) => {
    if (!validateWebhook(req)) {
        return res.status(401).json({ error: 'Unauthorized' });
    }
    
    const eventData = req.body;
    
    for (const event of eventData.data) {
        // Update contact in HubSpot based on link clicked
        const linkClicked = event.route.slashtag;
        
        if (linkClicked === 'pricing') {
            await axios.post('https://api.hubapi.com/contacts/v1/contact/email/{email}/profile', {
                properties: [
                    {
                        property: 'viewed_pricing',
                        value: 'true'
                    },
                    {
                        property: 'last_pricing_view',
                        value: event.timestamp
                    }
                ]
            }, {
                headers: { 'Authorization': `Bearer ${process.env.HUBSPOT_API_KEY}` }
            });
        }
    }
    
    res.status(200).json({ status: 'received' });
});

Ereignisse an Google Analytics 4 senden

import requests

def send_to_ga4(event):
    # GA4 Measurement Protocol
    ga4_endpoint = f"https://www.google-analytics.com/mp/collect?measurement_id={GA4_MEASUREMENT_ID}&api_secret={GA4_API_SECRET}"
    
    payload = {
        'client_id': event['key'],
        'events': [{
            'name': 'link_click',
            'params': {
                'slashtag': event['route']['slashtag'],
                'destination': event['route']['destination']['raw'],
                'country': event['client']['geo']['country'],
                'city': event['client']['geo']['city'],
                'device': event['client']['agent']['device']['name']
            }
        }]
    }
    
    response = requests.post(ga4_endpoint, json=payload)
    return response.status_code == 204

@app.route('/webhook', methods=['POST'])
def webhook_handler():
    if not validate_webhook(request):
        return jsonify({'error': 'Unauthorized'}), 401
    
    event_data = request.get_json()
    
    for event in event_data['data']:
        send_to_ga4(event)
    
    return jsonify({'status': 'received'}), 200

Poste Benachrichtigungen auf Slack

app.post('/webhook', async (req, res) => {
    if (!validateWebhook(req)) {
        return res.status(401).json({ error: 'Unauthorized' });
    }
    
    const eventData = req.body;
    
    for (const event of eventData.data) {
        // Alert team when specific links get clicked
        const linkClicked = event.route.slashtag;
        const location = `${event.client.geo.city}, ${event.client.geo.country}`;
        
        if (linkClicked === 'product-demo') {
            await axios.post(process.env.SLACK_WEBHOOK_URL, {
                text: `🎯 Product demo link clicked!\nLocation: ${location}\nTime: ${event.timestamp}`
            });
        }
    }
    
    res.status(200).json({ status: 'received' });
});

‍

Problembehebung

Problem: Veranstaltungen kommen nicht an

Prüfen Sie:

• Ist Ihr Endpunkt über das öffentliche Internet zugänglich? (Test mit Curl oder Postman)
• Gibt ihr 200-299 Statuscodes zurück?
• Reagiert Ihr Endpunkt innerhalb von 30 Sekunden?
• Hast du den Webhook im richtigen Workspace erstellt?

Problem: Authentifizierung schlägt fehl

Prüfen Sie:

• Ist der geheime Schlüssel korrekt in Ihren Umgebungsvariablen gespeichert?
• Liest du den Apikey-Header richtig? (Bei Header-Namen wird nicht zwischen Groß- und Kleinschreibung unterschieden, in einigen Frameworks müssen sie jedoch möglicherweise klein geschrieben werden.)
• Hast du das vollständige Geheimnis aus dem Rebrandly-Dashboard kopiert?

Problem: Ereignisse kommen nicht in der richtigen Reihenfolge an

Das wird erwartet. Verwenden Sie das Zeitstempelfeld, um Ereignisse korrekt zu sortieren. Machen Sie Ihre Datenbankoperationen idempotent, damit die doppelte Verarbeitung desselben Ereignisses keine Probleme verursacht.

Problem: Fehlende Ereignisse während einer Ausfallzeit

Fehlgeschlagene Lieferungen werden nicht erneut versucht. Wenn Ihr Endpunkt ausgefallen war, gehen diese Ereignisse verloren. Optionen:

• Integrieren Sie Redundanz in Ihren Endpunkt (mehrere Server, Zustandsprüfungen)
• Überwachen Sie die Webhook-Lieferraten und warnen Sie bei Drops
• In kritischen Anwendungsfällen sollten Sie die Webhook-Daten mit den Daten in der App abgleichen. Die Aufbewahrungsfrist für ältere Klicks beträgt 30 Tage.

Problem: Timeout-Fehler

Die Antwort Ihres Endpunkts dauert länger als 30 Sekunden. Lösung:

• Nehmen Sie das Ereignis sofort an und geben Sie 200€ zurück
• Das Ereignis für die asynchrone Verarbeitung in die Warteschlange stellen
• Machen Sie keine synchronen API-Aufrufe oder langen Datenbankabfragen in Ihrem Webhook-Handler

FAQ

Kann ich filtern, welche Ereignisse ich erhalte?

Noch nicht. Webhooks senden alle Klickereignisse aus dem konfigurierten Workspace. Filtere auf deiner Seite anhand von Slashtag, Ziel-URL oder anderen Payload-Feldern.

Welche Ereignistypen werden unterstützt?

Klicken Sie jetzt einfach auf Ereignisse. Wir untersuchen die Erstellung von Links, Link-Updates und Veranstaltungen mit Workspace-Aktivitäten für zukünftige Versionen.

Kann ich denselben Endpunkt für mehrere Workspaces verwenden?

Ja, aber du musst für jeden Workspace eine separate Webhook-Konfiguration erstellen. Verwenden Sie das Schlüsselfeld in der Payload, um zu identifizieren, welcher Webhook das Ereignis gesendet hat.

Funktionieren Webhooks mit QR-Codes?

Ja. QR-Code-Scans lösen dieselben Klickereignisse aus wie direkte Link-Klicks.

Werden Ereignisse wiederholt, wenn mein Endpunkt ausfällt?

Nein. Wir wiederholen Ereignisse nicht. Jeder wird einmal gesendet. Gestalten Sie Ihren Endpunkt auf Zuverlässigkeit.

Kann ich den Lieferverlauf sehen?

Ja. Öffnen Sie im Rebrandly-Dashboard Ihre Webhook-Details, um die letzten Zustellversuche, Erfolgsraten und Antwortcodes einzusehen. Der Verlauf der letzten 30 Tage wird gespeichert.

Was du bauen kannst

Analytik in Echtzeit: Streamen Sie Klickereignisse direkt in Google Analytics 4, Segment oder Ihr Data Warehouse. Sehen Sie sich die Kampagnenleistung zusammen mit anderen Kennzahlen an, ohne die Plattform zu wechseln.

Automatisierte Arbeitsabläufe: Löst E-Mail-Sequenzen aus, wenn potenzielle Kunden auf Preisseiten klicken. Aktualisieren Sie die Lead-Scores in Ihrem CRM auf der Grundlage der Interaktionen mit Inhalten. Sende Slack-Benachrichtigungen, wenn Kampagnen die Traffic-Schwellenwerte erreichen.

Benutzerdefinierte Geschäftslogik: Leiten Sie Klickdaten an interne Tools weiter, lösen Sie komplexe mehrstufige Workflows aus oder kombinieren Sie Klickereignisse mit anderen Datenquellen für benutzerdefinierte Attributionsmodelle.

Webhooks automatisieren den Datenfluss, für den zuvor manuelle Exporte erforderlich waren. Im Vergleich zu Batch-Exporten reduzieren Webhooks die manuelle Dateneingabe um 95%. Im Vergleich zu Polling liefern Webhooks Ereignisse, sobald sie eintreten — weniger API-Aufrufe, keine Verzögerungen, geringere Infrastrukturkosten.

Erste Schritte

1. Einen Webhook erstellen in Rebrandly: Gehe zu Kontoeinstellungen > Webhooks
2. Richten Sie Ihren Endpunkt ein mit einem der obigen Codebeispiele
3. Speichere den geheimen Schlüssel in Ihren Umgebungsvariablen
4. Testen Sie es mit dem Button „Testevent senden“
5. Bereitstellen und fange an, echte Klickereignisse zu erhalten

Fangen Sie einfach an: Erstellen Sie einen Endpunkt, der Ereignisse protokolliert. Fügen Sie dann die Geschäftslogik hinzu, die Sie benötigen — Datenbankspeicher, API-Aufrufe, Workflow-Trigger.

Fragen? Wenden Sie sich an den Rebrandly-Support oder besuchen Sie unsere API-Dokumentation.