Anleitung zur Webhook-Konfiguration

Was ist ein Webhook?

Webhook ermöglicht es SNSTracker, automatisch Benachrichtigungen an Ihren Server oder Ihre Anwendung zu senden, wenn überwachte Inhalte Ihre konfigurierten Schwellenwerte erreichen. Zum Beispiel, wenn die Aufrufe eines Videos deutlich steigen oder wenn ein Kanal neue Follower gewinnt, sendet SNSTracker eine Benachrichtigung an Ihre Webhook-URL (in der Regel innerhalb von 1 Minute).

Schritt-für-Schritt-Anleitung zur Konfiguration

Schritt 1: Webhook-Endpunkt vorbereiten

Bevor Sie in SNSTracker konfigurieren, benötigen Sie einen Webhook-Endpunkt. Das ist eine URL, die HTTP-POST-Anfragen empfangen kann.

Optionen für Ihren Webhook-Endpunkt:

Eigener Server: https://api.yourcompany.com/webhook
Cloud Functions: AWS Lambda, Google Cloud Functions, Azure Functions usw.
Automatisierungsplattformen: Zapier, Make.com, n8n usw.
Testdienste: webhook.site (nur zum Testen)

Anforderungen:

Muss HTTPS verwenden (URL beginnt mit https://)
Muss POST-Anfragen akzeptieren
Sollte bei Erfolg HTTP-Statuscode 200–299 zurückgeben

Schritt 2: Webhook-Ziel in SNSTracker hinzufügen

Zur Collections-Seite navigieren
- Bei SNSTracker anmelden
- In der linken Seitenleiste (unter Track) auf Collections klicken
- Oder direkt aufrufen: /dashboard/collections
Manage Notify Targets öffnen
- Auf der Collections-Seite die Schaltfläche "Manage Notify Targets" finden und anklicken
- Dadurch öffnet sich der Dialog zur Verwaltung der Benachrichtigungsziele
Neues Ziel hinzufügen
- Auf die Schaltfläche "Add Target" klicken
- Es erscheint ein Dialog zum Erstellen eines neuen Benachrichtigungsziels
Webhook-Typ auswählen
- Im Dialog das Dropdown "Type" finden
- "Webhook" aus den Optionen auswählen
Webhook-URL eingeben
- Im Feld "Webhook URL" die Webhook-Endpunkt-URL eingeben
- Beispiel: https://api.yourcompany.com/webhook
- Wichtig: Die URL muss mit https:// beginnen
Kommentar hinzufügen (optional)
- Im Feld "Comment" können Sie eine Notiz hinzufügen, wofür dieser Webhook gedacht ist
- Beispiel: "Produktions-Webhook für TikTok-Monitoring"
- Maximal 50 Zeichen
Signaturschlüssel konfigurieren (optional, für Produktion empfohlen)
- Im Feld "Extra" können Sie ein JSON-Objekt mit einem Signaturschlüssel hinzufügen:
```
{
  "signature_key": "your-secret-key-here"
}
```
- Dieser Schlüssel wird verwendet, um zu verifizieren, dass die Requests authentisch sind
- Wenn nicht angegeben, verwendet SNSTracker Ihren API-Key oder die Webhook-URL als Signaturschlüssel
Webhook-Ziel speichern
- Auf "Save" klicken
- Ihr Webhook-Ziel ist nun erstellt und einsatzbereit

Schritt 3: Benachrichtigungsregeln in der Collection konfigurieren

Collection-Einstellungen öffnen
- Zurück zur Collections-Seite gehen
- Die Collection finden, für die Sie Benachrichtigungen konfigurieren möchten
- Auf Edit klicken (oder auf den Collection-Namen klicken, um die Einstellungen zu öffnen)
Feed Notify aktivieren (für Videos/Posts)
- In den Collection-Einstellungen den Abschnitt "Feed Notify" finden
- Den Schalter "Enable Notifications" auf ON stellen
- Ihr Webhook-Ziel im Dropdown "Notify Targets" auswählen
- Die "Metrics" auswählen, die überwacht werden sollen:
  - Views
  - Engagement (likes + comments + shares)
- Den "Threshold"-Wert festlegen:
  - Eine Zahl eingeben (z. B. 1000), um zu benachrichtigen, wenn die Metrik um diesen Wert steigt
  - Auf 0 setzen, um nach jedem erfolgreichen Refresh zu benachrichtigen
- "Save" oder "Update" klicken
Channel Notify aktivieren (für Accounts)
- In denselben Collection-Einstellungen den Abschnitt "Channel Notify" finden
- Den Schalter "Enable Notifications" auf ON stellen
- Ihr Webhook-Ziel im Dropdown "Notify Targets" auswählen
- Die "Metrics" auswählen, die überwacht werden sollen:
  - Followers
  - Followings
  - Likes
- Den "Threshold"-Wert festlegen:
  - Eine Zahl eingeben (z. B. 500), um zu benachrichtigen, wenn die Metrik um diesen Wert steigt
  - Auf 0 setzen, um nach jedem erfolgreichen Refresh zu benachrichtigen
- "Save" oder "Update" klicken
Konfiguration prüfen
- Stellen Sie sicher, dass sowohl das Webhook-Ziel als auch die Benachrichtigungsregeln gespeichert sind
- Ihr Webhook erhält nun Benachrichtigungen, wenn die konfigurierten Schwellenwerte erreicht werden

Schritt 4: Webhook testen

Einen Testdienst verwenden (empfohlen beim ersten Setup)
- webhook.site besuchen
- Die bereitgestellte eindeutige URL kopieren (z. B. https://webhook.site/unique-id)
- Diese URL in Schritt 2 als Webhook-URL verwenden
- Eine Benachrichtigung mit Schwellenwert 0 konfigurieren (um bei jeder Änderung auszulösen)
- Warten, bis SNSTracker Ihre Inhalte prüft
- Auf webhook.site prüfen, ob die Benachrichtigung eingegangen ist
Endpoint-Logs prüfen
- Bei eigenem Server die Server-Logs prüfen
- Nach eingehenden POST-Requests von SNSTracker suchen
- Prüfen, ob der Request-Body die erwarteten Daten enthält
Benachrichtigungsformat verifizieren
- Die Benachrichtigung sollte ein JSON-Objekt sein mit:
  - title: Beschreibung der Benachrichtigung
  - type: Entweder "feed" oder "channel"
  - timestamp: Zeitpunkt, zu dem die Benachrichtigung gesendet wurde
  - data: Array der Elemente, die die Benachrichtigung ausgelöst haben

Wie Webhook-Benachrichtigungen gesendet werden

SNSTracker verwendet einen Batching-Mechanismus, um die Webhook-Zustellung zu optimieren:

Sofortige Erkennung: Wenn eine überwachte Ressource (Feed oder Channel) erfolgreich aktualisiert wird und Ihren Schwellenwert erreicht, wird sie sofort für die Benachrichtigung markiert.
1-Minuten-Batch-Fenster: Statt einzelne Benachrichtigungen sofort zu senden, sammelt SNSTracker alle berechtigten Benachrichtigungen innerhalb eines 1‑Minuten‑Fensters.
Konsolidierte Zustellung: Am Ende jedes 1‑Minuten‑Zeitfensters werden alle Benachrichtigungen aus diesem Fenster zu einer einzigen Webhook-Anfrage zusammengeführt und gemeinsam gesendet.

Beispielszenario:

Um 10:00:15 erreicht Feed A den Schwellenwert → markiert
Um 10:00:45 erreicht Feed B den Schwellenwert → markiert
Um 10:01:00 werden sowohl Feed A als auch Feed B in einer Webhook-Anfrage gesendet

Vorteile:

Reduziert die Anzahl der HTTP-Anfragen an Ihren Endpunkt
Steigert die Effizienz und reduziert die Serverlast
Verhindert Benachrichtigungsspam bei schnellen Datenänderungen
Alle Benachrichtigungen innerhalb des Batch-Zeitraums sind im data-Array enthalten

Hinweis: Die maximale Verzögerung zwischen dem Erreichen des Schwellenwerts und dem Versand des Webhooks beträgt 1 Minute. Das gewährleistet nahezu Echtzeit-Benachrichtigungen bei gleichzeitiger Systemeffizienz.

Welche Daten erhalten Sie?

Wenn eine Benachrichtigung ausgelöst wird, erhalten Sie eine POST-Anfrage mit JSON-Daten wie folgt:

{
  "title": "SNSTracker Notification: Feed Views Increased",
  "type": "feed",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": [
    {
      "feed_id": "feed-123",
      "url": "https://www.tiktok.com/@user/video/123",
      "platform_name": "TikTok",
      "view_count": 10000,
      "like_count": 2000,
      "changed_views": 1000,
      "changed_engagement": 50
    }
  ]
}

Datenfelder für Feed-Benachrichtigungen

feed_id: Eindeutige Kennung
url: Direkter Link zum Video/Beitrag
platform_name: Plattform (TikTok, Instagram usw.)
title: Inhaltstitel
description: Inhaltsbeschreibung
author_username: Benutzername des Creators
author_nickname: Anzeigename des Creators
view_count: Gesamtaufrufe
like_count: Gesamt-Likes
comment_count: Gesamtkommentare
share_count: Gesamt-Teilungen
changed_views: Zunahme der Aufrufe seit der letzten Prüfung
changed_engagement: Zunahme des Engagements (likes + comments + shares)

Datenfelder für Channel-Benachrichtigungen

id: Eindeutige Channel-Kennung
channel_url: Direkter Link zum Kanal/Profil
platform_name: Plattformname
nickname: Anzeigename
username: Benutzername/Handle
followers: Gesamtzahl der Follower
followings: Gesamtzahl der abonnierten Accounts
likes: Gesamt-Likes
changed_followers: Zunahme der Follower seit der letzten Prüfung
changed_followings: Zunahme der Followings seit der letzten Prüfung
changed_likes: Zunahme der Likes seit der letzten Prüfung

Sicherheit: Signaturprüfung

SNSTracker enthält eine Signatur im X-Signature-Header, um die Authentizität der Requests zu verifizieren. Der Signaturschlüssel wird wie folgt bestimmt:

Der signature_key im Feld Extra (falls angegeben)
Ihr erster aktiver API-Key (falls kein signature_key gesetzt ist)
Ihre Webhook-URL (als Fallback)

Für den produktiven Einsatz wird empfohlen, die Signatur zu prüfen, um sicherzustellen, dass die Requests authentisch sind.

Fehlerbehebung

Webhook erhält keine Benachrichtigungen

Webhook-URL prüfen
- Verifizieren Sie, dass die URL korrekt und erreichbar ist
- Stellen Sie sicher, dass sie mit https:// beginnt
- Testen Sie die URL manuell mit einer POST-Anfrage
Benachrichtigungseinstellungen prüfen
- Verifizieren Sie, dass Benachrichtigungen in Ihrer Collection aktiviert sind
- Prüfen Sie, dass das Webhook-Ziel ausgewählt ist
- Stellen Sie sicher, dass die Schwellenwerte korrekt gesetzt sind
Endpoint-Status prüfen
- Stellen Sie sicher, dass Ihr Endpunkt läuft und erreichbar ist
- Prüfen Sie Server-Logs auf eingehende Requests
- Verifizieren Sie, dass Ihr Endpunkt einen Erfolgsstatus (200–299) zurückgibt

Häufige Probleme

Problem: "Webhook URL already exists"
Lösung: Jede Webhook-URL kann pro Team nur einmal verwendet werden. Verwenden Sie eine andere URL oder bearbeiten Sie das bestehende Ziel.

Problem: Benachrichtigungen werden nicht ausgelöst
Lösung:

Schwellenwert auf 0 setzen, um zu testen (benachrichtigt bei jeder Änderung)
Warten, bis SNSTracker Ihre Inhalte prüft (die Prüfung erfolgt periodisch)
Verifizieren Sie, dass sich Ihre Inhalte tatsächlich um den Schwellenwertbetrag geändert haben

Problem: Timeout-Fehler
Lösung: Ihr Endpunkt muss innerhalb von 30 Sekunden antworten. Optimieren Sie die Antwortzeit Ihres Endpunkts.

Hilfe benötigt?

Wenn Sie auf Probleme stoßen:

Verifizieren Sie, dass Ihre Webhook-URL erreichbar ist
Prüfen Sie, ob die Benachrichtigungseinstellungen aktiviert sind
Stellen Sie sicher, dass die Schwellenwerte korrekt konfiguriert sind
Kontaktieren Sie den Support, wenn Probleme weiterhin bestehen

Viel Erfolg beim Tracking! 🚀

Anleitung zur Webhook-Konfiguration

On this page