Guida alla configurazione dei webhook

Che cos'è un webhook?

Webhook consente a SNSTracker di inviare automaticamente notifiche al tuo server o alla tua applicazione quando i contenuti monitorati raggiungono le soglie configurate. Ad esempio, quando le visualizzazioni di un video aumentano in modo significativo o quando un canale acquisisce nuovi follower, SNSTracker invierà una notifica al tuo URL webhook (di solito entro 1 minuto).

Guida alla configurazione passo passo

Passo 1: Prepara il tuo endpoint webhook

Prima di configurare SNSTracker, devi avere un endpoint webhook pronto. Si tratta di un URL in grado di ricevere richieste HTTP POST.

Opzioni per il tuo endpoint webhook:

Il tuo server: https://api.yourcompany.com/webhook
Funzioni cloud: AWS Lambda, Google Cloud Functions, Azure Functions, ecc.
Piattaforme di automazione: Zapier, Make.com, n8n, ecc.
Servizi di test: webhook.site (solo per test)

Requisiti:

Deve usare HTTPS (l’URL inizia con https://)
Deve accettare richieste POST
Deve restituire un codice di stato HTTP 200-299 in caso di successo

Passo 2: Aggiungi un target webhook in SNSTracker

Vai alla pagina Collections
- Accedi a SNSTracker
- Clicca su Collections nella barra laterale sinistra (sotto la sezione Track)
- Oppure vai direttamente a: /dashboard/collections
Apri Manage Notify Targets
- Nella pagina Collections, trova e clicca il pulsante "Manage Notify Targets"
- Si apre la finestra di gestione dei target di notifica
Aggiungi un nuovo target
- Clicca sul pulsante "Add Target"
- Apparirà una finestra per creare un nuovo target di notifica
Seleziona il tipo Webhook
- Nella finestra, trova il menu a discesa "Type"
- Seleziona "Webhook" dalle opzioni
Inserisci l’URL del webhook
- Nel campo "Webhook URL", inserisci l’URL del tuo endpoint webhook
- Esempio: https://api.yourcompany.com/webhook
- Importante: l’URL deve iniziare con https://
Aggiungi un commento (opzionale)
- Nel campo "Comment", puoi aggiungere una nota per ricordare a cosa serve questo webhook
- Esempio: "Webhook di produzione per il monitoraggio TikTok"
- Massimo 50 caratteri
Configura la chiave di firma (opzionale, consigliata in produzione)
- Nel campo "Extra", puoi aggiungere un oggetto JSON con una chiave di firma:
```
{
  "signature_key": "your-secret-key-here"
}
```
- Questa chiave verrà utilizzata per verificare che le richieste siano autentiche
- Se non viene fornita, SNSTracker userà la tua API key o l’URL del webhook come chiave di firma
Salva il target webhook
- Clicca sul pulsante "Save"
- Il tuo target webhook è ora creato e pronto all’uso

Passo 3: Configura le regole di notifica nella Collection

Apri le impostazioni della Collection
- Torna alla pagina Collections
- Trova la collection per cui vuoi configurare le notifiche
- Clicca su Edit (oppure clicca sul nome della collection per aprire le impostazioni)
Abilita Feed Notify (per video/post)
- Nelle impostazioni della collection, trova la sezione "Feed Notify"
- Attiva l’interruttore "Enable Notifications"
- Seleziona il tuo target webhook dal menu a discesa "Notify Targets"
- Scegli le "Metrics" che vuoi monitorare:
  - Visualizzazioni
  - Engagement (like + commenti + condivisioni)
- Imposta il valore "Threshold":
  - Inserisci un numero (ad es. 1000) per notificare quando la metrica aumenta di tale valore
  - Imposta a 0 per notificare dopo ogni aggiornamento riuscito
- Clicca su "Save" o "Update"
Abilita Channel Notify (per account)
- Nelle stesse impostazioni della collection, trova la sezione "Channel Notify"
- Attiva l’interruttore "Enable Notifications"
- Seleziona il tuo target webhook dal menu a discesa "Notify Targets"
- Scegli le "Metrics" che vuoi monitorare:
  - Follower
  - Seguiti
  - Like
- Imposta il valore "Threshold":
  - Inserisci un numero (ad es. 500) per notificare quando la metrica aumenta di tale valore
  - Imposta a 0 per notificare dopo ogni aggiornamento riuscito
- Clicca su "Save" o "Update"
Verifica la configurazione
- Assicurati che siano salvati sia il target webhook sia le regole di notifica
- Il tuo webhook ora riceverà notifiche quando vengono raggiunte le soglie configurate

Passo 4: Testa il tuo webhook

Usa un servizio di test (consigliato per la prima configurazione)
- Visita webhook.site
- Copia l’URL univoco fornito (ad es. https://webhook.site/unique-id)
- Usa questo URL come webhook URL nel Passo 2
- Configura una notifica con soglia 0 (per attivarla su qualsiasi cambiamento)
- Attendi che SNSTracker controlli i tuoi contenuti
- Controlla webhook.site per vedere se hai ricevuto la notifica
Controlla i log del tuo endpoint
- Se usi il tuo server, controlla i log del server
- Cerca le richieste POST in arrivo da SNSTracker
- Verifica che il corpo della richiesta contenga i dati previsti
Verifica il formato della notifica
- La notifica dovrebbe essere un oggetto JSON con:
  - title: Descrizione della notifica
  - type: "feed" oppure "channel"
  - timestamp: Quando è stata inviata la notifica
  - data: Array di elementi che hanno attivato la notifica

Come vengono inviate le notifiche webhook

SNSTracker utilizza un meccanismo di batch per ottimizzare l’invio dei webhook:

Rilevamento immediato: Quando una risorsa monitorata (feed o canale) viene aggiornata con successo e raggiunge la soglia di notifica, viene subito contrassegnata per la notifica.
Finestra batch di 1 minuto: Invece di inviare subito notifiche singole, SNSTracker accumula tutte le notifiche idonee in una finestra di 1 minuto.
Invio consolidato: Alla fine di ogni periodo di 1 minuto, tutte le notifiche di quella finestra vengono unite in una singola richiesta webhook e inviate insieme.

Scenario di esempio:

Alle 10:00:15, il Feed A raggiunge la soglia → contrassegnato
Alle 10:00:45, il Feed B raggiunge la soglia → contrassegnato
Alle 10:01:00, sia il Feed A che il Feed B vengono inviati in una sola richiesta webhook

Vantaggi:

Riduce il numero di richieste HTTP al tuo endpoint
Migliora l’efficienza e riduce il carico del server
Previene lo spam di notifiche durante rapidi cambiamenti dei dati
Tutte le notifiche nel periodo di batch sono incluse nell’array data

Nota: Il ritardo massimo tra il raggiungimento della soglia da parte di una risorsa e l’invio del webhook è di 1 minuto. Questo garantisce notifiche quasi in tempo reale mantenendo l’efficienza del sistema.

Quali dati riceverai?

Quando viene attivata una notifica, riceverai una richiesta POST con dati JSON come questi:

{
  "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
    }
  ]
}

Campi dati della notifica Feed

feed_id: Identificatore univoco
url: Link diretto al video/post
platform_name: Piattaforma (TikTok, Instagram, ecc.)
title: Titolo del contenuto
description: Descrizione del contenuto
author_username: Username del creator
author_nickname: Nome visualizzato del creator
view_count: Visualizzazioni totali
like_count: Like totali
comment_count: Commenti totali
share_count: Condivisioni totali
changed_views: Incremento delle visualizzazioni dall’ultimo controllo
changed_engagement: Incremento dell’engagement (like + commenti + condivisioni)

Campi dati della notifica Channel

id: Identificatore univoco del canale
channel_url: Link diretto al canale/profilo
platform_name: Nome della piattaforma
nickname: Nome visualizzato
username: Username/handle
followers: Follower totali
followings: Account seguiti totali
likes: Like totali
changed_followers: Incremento dei follower dall’ultimo controllo
changed_followings: Incremento dei seguiti dall’ultimo controllo
changed_likes: Incremento dei like dall’ultimo controllo

Sicurezza: verifica della firma

SNSTracker include una firma nell’header X-Signature per verificare l’autenticità delle richieste. La chiave di firma è determinata da:

La signature_key nel campo Extra (se fornita)
La tua prima API key attiva (se non è impostata una signature_key)
Il tuo URL webhook (come fallback)

Per l’uso in produzione, si consiglia di verificare la firma per assicurarsi che le richieste siano autentiche.

Risoluzione dei problemi

Il webhook non riceve notifiche

Controlla l’URL del webhook
- Verifica che l’URL sia corretto e accessibile
- Assicurati che inizi con https://
- Testa l’URL manualmente con una richiesta POST
Controlla le impostazioni di notifica
- Verifica che le notifiche siano abilitate nella tua Collection
- Controlla che il target webhook sia selezionato
- Assicurati che le soglie siano impostate correttamente
Controlla lo stato dell’endpoint
- Assicurati che il tuo endpoint sia in esecuzione e accessibile
- Controlla i log del server per le richieste in arrivo
- Verifica che il tuo endpoint restituisca uno stato di successo (200-299)

Problemi comuni

Problema: "Webhook URL already exists"
Soluzione: Ogni URL webhook può essere usato una sola volta per team. Usa un URL diverso o modifica il target esistente.

Problema: Le notifiche non si attivano
Soluzione:

Imposta la soglia a 0 per testare (notifica su qualsiasi cambiamento)
Attendi che SNSTracker controlli i tuoi contenuti (il controllo avviene periodicamente)
Verifica che i tuoi contenuti siano effettivamente cambiati dell’importo della soglia

Problema: Errori di timeout
Soluzione: Il tuo endpoint deve rispondere entro 30 secondi. Ottimizza i tempi di risposta del tuo endpoint.

Serve aiuto?

Se riscontri problemi:

Verifica che il tuo URL webhook sia accessibile
Controlla che le impostazioni di notifica siano abilitate
Assicurati che le soglie siano configurate correttamente
Contatta l’assistenza se i problemi persistono

Buon tracking! 🚀

Guida alla configurazione dei webhook

On this page