Webhooks

Recevez une requête HTTP POST signée chaque fois qu’un événement se produit dans un projet, sans avoir à interroger l’API. Les webhooks alimentent les connecteurs LLM Pulse pour Zapier, Make et n8n, et fonctionnent avec n’importe quel backend sur mesure. Disponible à partir du forfait Scale.

  • Types d’événements : mention.created, competitor_mention.created, citation.created, prompt_execution.completed, sentiment.negative_detected (sentiment négatif ou très négatif envers la marque), recommendation.completed, intelligence_task.completed, intelligence_task.updated (une tâche GEO Writer terminée a été modifiée à la main ou rétablie dans sa version générée par l’IA), geo_audit_run.completed (une exécution d’audit GEO est terminée, quel qu’en soit le résultat), geo_audit_alert.triggered (une exécution planifiée d’audit GEO a déclenché une alerte, par exemple un contrôle critique désormais en échec, une baisse du score ou un site qui ne répond plus), tracking_run.completed (une exécution de suivi du projet est terminée et ses données sont prêtes à être lues).
  • Sécurité : chaque envoi comporte les en-têtes X-LLMPulse-Event, X-LLMPulse-Delivery (identifiant unique) et X-LLMPulse-Signature (sha256=<hex>, HMAC-SHA256 du corps brut calculé avec le secret de l’abonnement). Vérifiez la signature pour authentifier les envois.
  • Envoi : une réponse 2xx accuse réception de l’événement ; sinon, l’envoi est tenté jusqu’à 5 fois au total, premier essai compris, avec un délai exponentiel entre les tentatives. Un abonnement se désactive automatiquement après 20 échecs d’envoi consécutifs.

POST/webhooks

Crée un abonnement. Idempotent : un nouvel appel avec le même projet, le même événement et la même URL renvoie l’abonnement existant, sauf si la clé API ou la connexion OAuth qui l’a créé a été révoquée ; il est alors remplacé par un nouvel abonnement doté d’un nouveau secret. Le secret de signature (whsec_...) n’est renvoyé que par cet endpoint : conservez-le pour vérifier la signature des envois. Nécessite une clé de portée read_write.

  • Corps (JSON) : project_id (obligatoire), event_type (obligatoire, voir la liste des événements ci-dessus), target_url (obligatoire, URL HTTPS publique ; les adresses IP privées, localhost et les noms d’hôte internes sont refusés). 100 abonnements actifs au maximum par compte.

GET/webhooks

Liste les abonnements actifs du compte. Les éléments reprennent la réponse de création, sans le secret. Avec une clé API en lecture seule, chaque target_url est masquée et réduite à son schéma, son hôte et son éventuel port non standard, suivis de /…, car l’URL complète peut permettre à n’importe qui d’envoyer des requêtes au récepteur ; une clé de portée read_write reçoit l’URL complète.

Paramètres :
  • project_idfiltre facultatif
  • page
  • per_page100 maximum

DELETE/webhooks/:id

Supprime un abonnement. L’URL cible cesse immédiatement de recevoir des événements. Nécessite une clé de portée read_write.

Chemin :
  • :ididentifiant de l’abonnement

Renvoie ERR_NOT_FOUND pour les abonnements qui n’appartiennent pas au compte.

GET/webhooks/sample/:event_type

Jusqu’à 3 exemples de payloads pour le type d’événement, construits à partir des données réelles les plus récentes du projet (ou un exemple statique si le projet n’a pas encore de données). Utilisé par les outils de création d’intégrations, comme le chargeur d’exemples de Zapier. Également disponible via l’outil MCP get_webhook_sample.

Paramètres :
  • :event_typechemin
  • project_idobligatoire