Guide de configuration du webhook

Qu’est-ce qu’un webhook ?

Webhook permet à SNSTracker d’envoyer automatiquement des notifications à votre serveur ou application lorsque le contenu surveillé atteint les seuils que vous avez configurés. Par exemple, lorsque les vues d’une vidéo augmentent significativement ou lorsqu’une chaîne gagne de nouveaux abonnés, SNSTracker enverra une notification à votre URL de webhook (généralement en moins d’1 minute).

Guide de configuration étape par étape

Étape 1 : Préparer votre endpoint webhook

Avant de configurer dans SNSTracker, vous devez disposer d’un endpoint webhook prêt. Il s’agit d’une URL qui peut recevoir des requêtes HTTP POST.

Options pour votre endpoint webhook :

Votre propre serveur : https://api.yourcompany.com/webhook
Fonctions cloud : AWS Lambda, Google Cloud Functions, Azure Functions, etc.
Plateformes d’automatisation : Zapier, Make.com, n8n, etc.
Services de test : webhook.site (uniquement pour les tests)

Exigences :

Doit utiliser HTTPS (l’URL commence par https://)
Doit accepter les requêtes POST
Doit renvoyer un code de statut HTTP 200-299 en cas de succès

Étape 2 : Ajouter une cible webhook dans SNSTracker

Accéder à la page Collections
- Connectez-vous à SNSTracker
- Cliquez sur Collections dans la barre latérale gauche (sous la section Track)
- Ou allez directement à : /dashboard/collections
Ouvrir la gestion des cibles de notification
- Sur la page Collections, trouvez et cliquez sur le bouton "Manage Notify Targets"
- Cela ouvre la boîte de dialogue de gestion des cibles de notification
Ajouter une nouvelle cible
- Cliquez sur le bouton "Add Target"
- Une boîte de dialogue apparaîtra pour créer une nouvelle cible de notification
Sélectionner le type Webhook
- Dans la boîte de dialogue, trouvez la liste déroulante "Type"
- Sélectionnez "Webhook" parmi les options
Saisir l’URL du webhook
- Dans le champ "Webhook URL", saisissez l’URL de votre endpoint webhook
- Exemple : https://api.yourcompany.com/webhook
- Important : l’URL doit commencer par https://
Ajouter un commentaire (optionnel)
- Dans le champ "Comment", vous pouvez ajouter une note pour vous rappeler l’objectif de ce webhook
- Exemple : "Webhook de production pour le suivi TikTok"
- 50 caractères maximum
Configurer la clé de signature (optionnel, recommandé en production)
- Dans le champ "Extra", vous pouvez ajouter un objet JSON avec une clé de signature :
```
{
  "signature_key": "your-secret-key-here"
}
```
- Cette clé sera utilisée pour vérifier l’authenticité des requêtes
- Si elle n’est pas fournie, SNSTracker utilisera votre clé API ou l’URL du webhook comme clé de signature
Enregistrer la cible webhook
- Cliquez sur le bouton "Save"
- Votre cible webhook est maintenant créée et prête à l’emploi

Étape 3 : Configurer les règles de notification dans une collection

Ouvrir les paramètres de la collection
- Retournez sur la page Collections
- Trouvez la collection pour laquelle vous voulez configurer les notifications
- Cliquez sur le bouton Edit (ou cliquez sur le nom de la collection pour ouvrir les paramètres)
Activer Feed Notify (pour les vidéos/publications)
- Dans les paramètres de la collection, trouvez la section "Feed Notify"
- Passez l’interrupteur "Enable Notifications" sur ON
- Sélectionnez votre cible webhook dans la liste déroulante "Notify Targets"
- Choisissez les "Metrics" que vous souhaitez surveiller :
  - Views
  - Engagement (likes + comments + shares)
- Définissez la valeur "Threshold" :
  - Saisissez un nombre (par ex. 1000) pour être notifié lorsque la métrique augmente de ce montant
  - Définissez à 0 pour être notifié après chaque actualisation réussie
- Cliquez sur "Save" ou "Update"
Activer Channel Notify (pour les comptes)
- Dans les mêmes paramètres de la collection, trouvez la section "Channel Notify"
- Passez l’interrupteur "Enable Notifications" sur ON
- Sélectionnez votre cible webhook dans la liste déroulante "Notify Targets"
- Choisissez les "Metrics" que vous souhaitez surveiller :
  - Followers
  - Followings
  - Likes
- Définissez la valeur "Threshold" :
  - Saisissez un nombre (par ex. 500) pour être notifié lorsque la métrique augmente de ce montant
  - Définissez à 0 pour être notifié après chaque actualisation réussie
- Cliquez sur "Save" ou "Update"
Vérifier la configuration
- Assurez-vous que la cible webhook et les règles de notification sont bien enregistrées
- Votre webhook recevra maintenant des notifications lorsque les seuils configurés seront atteints

Étape 4 : Tester votre webhook

Utiliser un service de test (recommandé pour une première configuration)
- Visitez webhook.site
- Copiez l’URL unique fournie (ex. https://webhook.site/unique-id)
- Utilisez cette URL comme URL de webhook à l’étape 2
- Configurez une notification avec un seuil de 0 (pour déclencher à chaque changement)
- Attendez que SNSTracker vérifie votre contenu
- Vérifiez sur webhook.site si vous avez reçu la notification
Vérifier les logs de votre endpoint
- Si vous utilisez votre propre serveur, vérifiez les logs du serveur
- Recherchez les requêtes POST entrantes de SNSTracker
- Vérifiez que le corps de la requête contient les données attendues
Vérifier le format de la notification
- La notification doit être un objet JSON avec :
  - title : Description de la notification
  - type : Soit "feed" soit "channel"
  - timestamp : Moment où la notification a été envoyée
  - data : Tableau d’éléments ayant déclenché la notification

Comment les notifications webhook sont envoyées

SNSTracker utilise un mécanisme de regroupement pour optimiser l’envoi des webhooks :

Détection immédiate : Lorsqu’une ressource surveillée (feed ou channel) est actualisée avec succès et atteint votre seuil de notification, elle est immédiatement marquée pour notification.
Fenêtre de regroupement de 1 minute : Plutôt que d’envoyer des notifications individuelles immédiatement, SNSTracker regroupe toutes les notifications éligibles dans une fenêtre d’1 minute.
Livraison consolidée : À la fin de chaque période d’1 minute, toutes les notifications de cette fenêtre sont fusionnées en une seule requête webhook et envoyées ensemble.

Scénario d’exemple :

À 10:00:15, Feed A atteint le seuil → marqué
À 10:00:45, Feed B atteint le seuil → marqué
À 10:01:00, Feed A et Feed B sont envoyés dans une seule requête webhook

Avantages :

Réduit le nombre de requêtes HTTP vers votre endpoint
Améliore l’efficacité et réduit la charge serveur
Évite le spam de notifications lors de changements rapides des données
Toutes les notifications de la période de regroupement sont incluses dans le tableau data

Note : Le délai maximal entre l’atteinte du seuil par une ressource et l’envoi du webhook est d’1 minute. Cela garantit des notifications quasi en temps réel tout en maintenant l’efficacité du système.

Quelles données allez-vous recevoir ?

Lorsqu’une notification est déclenchée, vous recevrez une requête POST avec des données JSON comme ceci :

{
  "title": "Notification SNSTracker : vues du feed en hausse",
  "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
    }
  ]
}

Champs de données des notifications de feed

feed_id : Identifiant unique
url : Lien direct vers la vidéo/publication
platform_name : Plateforme (TikTok, Instagram, etc.)
title : Titre du contenu
description : Description du contenu
author_username : Nom d’utilisateur du créateur
author_nickname : Nom d’affichage du créateur
view_count : Total des vues
like_count : Total des likes
comment_count : Total des commentaires
share_count : Total des partages
changed_views : Vues augmentées depuis la dernière vérification
changed_engagement : Engagement augmenté (likes + commentaires + partages)

Champs de données des notifications de channel

id : Identifiant unique du channel
channel_url : Lien direct vers le channel/profil
platform_name : Nom de la plateforme
nickname : Nom d’affichage
username : Nom d’utilisateur/identifiant
followers : Total des abonnés
followings : Total des comptes suivis
likes : Total des likes
changed_followers : Abonnés gagnés depuis la dernière vérification
changed_followings : Abonnements gagnés depuis la dernière vérification
changed_likes : Likes gagnés depuis la dernière vérification

Sécurité : vérification de la signature

SNSTracker inclut une signature dans l’en-tête X-Signature pour vérifier l’authenticité des requêtes. La clé de signature est déterminée par :

Le signature_key dans le champ Extra (si fourni)
Votre première clé API active (si aucun signature_key n’est défini)
L’URL de votre webhook (en repli)

Pour une utilisation en production, il est recommandé de vérifier la signature afin de s’assurer que les requêtes sont authentiques.

Dépannage

Le webhook ne reçoit pas de notifications

Vérifier l’URL du webhook
- Vérifiez que l’URL est correcte et accessible
- Assurez-vous qu’elle commence par https://
- Testez l’URL manuellement avec une requête POST
Vérifier les paramètres de notification
- Vérifiez que les notifications sont activées dans votre Collection
- Vérifiez que la cible webhook est sélectionnée
- Assurez-vous que les seuils sont correctement définis
Vérifier l’état de l’endpoint
- Assurez-vous que votre endpoint fonctionne et est accessible
- Vérifiez les logs du serveur pour les requêtes entrantes
- Vérifiez que votre endpoint renvoie un statut de succès (200-299)

Problèmes fréquents

Problème : "Webhook URL already exists"
Solution : Chaque URL de webhook ne peut être utilisée qu’une seule fois par équipe. Utilisez une autre URL ou modifiez la cible existante.

Problème : Notifications non déclenchées
Solution :

Définissez le seuil à 0 pour tester (notification à chaque changement)
Attendez que SNSTracker vérifie votre contenu (les vérifications sont périodiques)
Vérifiez que votre contenu a effectivement changé du montant du seuil

Problème : Erreurs de délai d’attente
Solution : Votre endpoint doit répondre en 30 secondes. Optimisez le temps de réponse de votre endpoint.

Besoin d’aide ?

Si vous rencontrez des problèmes :

Vérifiez que l’URL de votre webhook est accessible
Vérifiez que les paramètres de notification sont activés
Assurez-vous que les seuils sont correctement configurés
Contactez le support si les problèmes persistent

Bon tracking ! 🚀

Guide de configuration du webhook

On this page