Utiliser les Webhooks

SalesMind AI peut envoyer des données d'événement à votre serveur au moment où quelque chose se produit — une demande de connexion part, un prospect accepte, un message est envoyé ou reçu, ou une conversation est taguée. Au lieu d'interroger l'API, votre endpoint reçoit une requête POST avec tout le contexte.

Ce guide vous montre comment configurer un endpoint de webhook, choisir les événements qui vous intéressent et traiter la charge utile.

Prérequis

• Un compte SalesMind AI avec au moins un sender actif
• Un endpoint HTTPS accessible publiquement capable de recevoir des requêtes POST

Comment fonctionnent les webhooks

SalesMind AI déclenche un webhook chaque fois qu'un événement pertinent se produit sur un fil de conversation de votre boîte de réception — qu'il soit déclenché par une action de campagne ou par une modification manuelle que vous faites dans l'interface. Chaque événement envoie une requête HTTP POST à l'URL que vous avez configurée.

Types d'événements disponibles

Type d'événement	Se déclenche quand…
activity.invitation.sent.v1	Une demande de connexion est envoyée à un prospect
activity.connection.accepted.v1	Un prospect accepte votre demande de connexion
activity.message.sent.v1	Un message est envoyé à un prospect (y compris les messages automatiques de campagne et les relances)
activity.message.received.v1	Un prospect répond à votre conversation
activity.threadbox.tags.update.v1	Un tag est ajouté ou retiré sur un fil de conversation

Ces cinq événements activity.* sont ceux qu'un compte normal peut souscrire et recevoir. Un sixième événement, user.register.v1, existe mais est réservé aux administrateurs — les comptes normaux ne le reçoivent jamais, et il est retiré automatiquement si vous essayez de le souscrire. webhook.test.v1 est un événement ponctuel envoyé par le bouton Test, et non un événement auquel vous vous abonnez.

Configurer votre endpoint de webhook

1. Dans la barre latérale gauche, cliquez sur l'icône d'engrenage Paramètres en bas.
2. Cliquez sur Webhooks.
3. Collez l'URL de votre endpoint HTTPS.
4. Choisissez les types d'événements que vous voulez recevoir.
5. Sélectionnez de quels agents vous voulez recevoir des événements.
6. Cliquez sur Enregistrer.

💡 Astuce : Utilisez le bouton Test pour envoyer une charge utile d'exemple à votre endpoint. Cela confirme que votre serveur peut recevoir des requêtes avant que de vrais événements ne se déclenchent.

Gérer les endpoints avec l'API

Vous pouvez gérer les endpoints de webhook via l'API plutôt que dans l'interface. Chaque endpoint nécessite votre en-tête X-API-KEY et se trouve sous https://api.sales-mind.ai//v1/webhooks.

Méthode	Endpoint	Objectif
POST	/v1/webhooks/endpoints	Enregistrer un nouvel endpoint
GET	/v1/webhooks/endpoints	Lister vos endpoints
GET	/v1/webhooks/endpoints/{id}	Récupérer un endpoint
DELETE	/v1/webhooks/endpoints/{id}	Supprimer un endpoint
GET	/v1/webhooks/endpoints/{id}/rotate-secret	Obtenir un nouveau secret de signature
PUT	/v1/webhooks/endpoints/{id}/suspend	Suspendre ou réactiver un endpoint
GET	/v1/webhooks/events	Lister les événements auxquels vous pouvez vous abonner
PUT	/v1/webhooks/endpoints/{id}/events	Modifier les événements souscrits
GET	/v1/webhooks/endpoints/{id}/test	Envoyer une livraison de test

⚠️ L'enregistrement ne renvoie pas votre secret de signature. Après avoir enregistré un endpoint, appelez rotate-secret pour récupérer le secret avec lequel vous vérifiez les livraisons.

Votre endpoint doit être une URL HTTPS publique. SalesMind AI le vérifie au moment de livrer un événement, pas à l'enregistrement — une URL non HTTPS ou privée est donc acceptée au départ puis échoue à la livraison.

Comprendre la charge utile

Chaque livraison de webhook envoie un objet JSON avec trois champs de premier niveau et un objet data imbriqué contenant tout le contexte.

Champs de premier niveau :

Champ	Description	Exemple
id	ID de livraison unique (utilisé comme clé d'idempotence)	df313559-7cb1-...
type	Le type d'événement	activity.connection.accepted.v1
timestamp	Quand l'événement s'est produit (ISO 8601)	2026-02-06T05:05:36+01:00

L'objet data contient ces sections :

Section	Ce qu'elle contient
data.agent	Le nom de votre agent, les détails de l'entreprise, les services, le ton de marque et le playbook commercial
data.campaign	ID de campagne, nom, statut, objectif, URL de la page produit, URL de la landing page et type de campagne
data.campaignContact	Statut du contact dans la campagne (p. ex. invitation_send), détails de la dernière activité et indicateur de fin
data.threadBox	Noms complets du sender et du contact, tableau de tags, statut de la conversation, fit score, justification de l'IA, nom de persona et statut de réponse
data.sender	Profil LinkedIn complet du compte émetteur, coordonnées de la base de connaissances et analyse de personnalité MBTI
data.contact	Profil LinkedIn du prospect, intitulé, résumé, localisation, compétences, entreprises actuelles et analyse MBTI
data.messages	Tableau des messages du fil de conversation

💡 Astuce : La charge utile complète est volumineuse et inclut tout le contexte de l'agent. Envoyez d'abord un webhook de test à votre endpoint, puis utilisez ce JSON pour mapper uniquement les champs dont vous avez besoin dans votre handler.

Vérifier la signature

Chaque livraison porte quatre en-têtes qui vous permettent de confirmer qu'elle vient bien de SalesMind AI :

En-tête	Valeur
Webhook-Signature	HMAC-SHA256 encodé en Base64 de la chaîne signée
Webhook-Timestamp	Secondes d'époque Unix, utilisées dans la chaîne signée
Webhook-Idempotency-Key	{eventId}:{endpointId} — utilisez-le pour écarter les livraisons en double
Webhook-Key-Id	current — quel secret de signature a été utilisé

La chaîne signée est :

{Webhook-Timestamp}.{endpointId}.{sha256_hex(rawBody)}

Signez la valeur de l'en-tête Webhook-Timestamp, et non le champ timestamp ISO à l'intérieur du corps — ils sont différents.

Pour vérifier une livraison :

1. Lisez le corps brut de la requête, l'en-tête Webhook-Timestamp et l'en-tête Webhook-Signature.
2. Calculez le condensé SHA-256 en hexadécimal du corps brut, puis construisez {Webhook-Timestamp}.{endpointId}.{sha256_hex}.
3. Calculez Base64(HMAC-SHA256(cette chaîne, le secret de votre endpoint)) et comparez-le à Webhook-Signature avec une comparaison à temps constant.
4. Facultatif : rejetez la livraison si Webhook-Timestamp est plus ancien qu'une fenêtre que vous choisissez (par exemple, 5 minutes).

💡 La fenêtre de rejeu de 5 minutes est une vérification que vous ajoutez de votre côté. SalesMind AI ne l'impose pas.

⚠️ Après avoir fait tourner votre secret, mettez à jour votre secret stocké rapidement. SalesMind AI signe toujours avec le secret actuel, donc les livraisons passent immédiatement au nouveau secret — il n'y a pas de période de grâce côté signature.

Vérifier l'historique des livraisons

Vous pouvez vérifier si un webhook s'est déclenché et consulter son statut de livraison directement dans l'application. Allez dans Paramètres → Webhooks pour voir les livraisons récentes, leurs codes de statut et leurs horodatages.

Vous pouvez aussi récupérer les livraisons via l'API :

Méthode	Endpoint	Objectif
GET	/v1/webhooks/deliveries	Lister les livraisons (filtrer par endpointId, status, type)
GET	/v1/webhooks/deliveries/{id}	Récupérer une livraison, avec sa charge utile
POST	/v1/webhooks/deliveries/{id}/replay	Rejouer une livraison en tant que nouvel événement

Chaque livraison a un statut : pending, delivered, failed ou suspended.

Comment fonctionnent les tentatives de livraison :

• Chaque tentative expire après 5 secondes.
• Une réponse 2xx marque la livraison comme delivered et réinitialise le compteur d'échecs de l'endpoint.
• Toute autre réponse — ou un délai dépassé — la marque comme failed et réessaie avec un backoff de 5, 10, 20, 60, puis 300 secondes (jusqu'à 5 tentatives, soit 6 tentatives au total).
• Après 10 échecs consécutifs, SalesMind AI suspend l'endpoint automatiquement. Les nouveaux événements pour un endpoint suspendu sont enregistrés comme suspended et ignorés jusqu'à ce que vous le réactiviez.

Pièges courants

« Le test fonctionne mais les vrais événements ne se déclenchent pas »

Assurez-vous d'avoir une campagne active avec des prospects qui avancent dans le workflow. Les webhooks se déclenchent quand le système effectue une action (envoie une invitation, envoie un message, reçoit une réponse, tague un fil) ou quand vous modifiez un tag manuellement. S'il n'y a aucune activité, il n'y a aucun événement à envoyer.

« Je reçois des événements mais il manque des champs dans la charge utile »

La charge utile varie légèrement selon le type d'événement. Un événement activity.invitation.sent.v1 n'aura pas de champs liés aux réponses, par exemple. Vérifiez la charge utile de test de votre type d'événement précis pour voir quels champs sont inclus.

« La charge utile est très volumineuse »

C'est attendu. Chaque livraison inclut tout le contexte de l'agent (services, playbook commercial, ton de marque) afin que votre handler ait tout ce qu'il faut pour router et traiter l'événement. N'analysez que les champs dont vous avez besoin.

« Mon URL d'endpoint a été acceptée mais ne reçoit jamais rien »

Votre endpoint doit être une URL HTTPS publique. SalesMind AI le vérifie au moment de livrer un événement, pas à l'enregistrement — une URL non HTTPS ou privée est donc acceptée au départ puis échoue à la livraison. Vérifiez votre historique des livraisons pour repérer les tentatives échouées.

Points clés

• Les webhooks envoient des données en temps réel à votre serveur quand des événements se produisent — aussi bien les actions automatiques de campagne que les changements manuels.
• Un compte normal souscrit aux cinq événements activity.* ; user.register.v1 est réservé aux administrateurs et webhook.test.v1 n'est que l'événement de test.
• Gérez les endpoints, les événements et les livraisons via l'API sous https://api.sales-mind.ai//v1/webhooks — authentifiez-vous avec X-API-KEY.
• Vérifiez chaque livraison avec les en-têtes Webhook-Signature et Webhook-Timestamp ; le secret de signature vient de rotate-secret, pas de l'enregistrement.
• Les livraisons sont réessayées avec un backoff et un endpoint est suspendu après 10 échecs consécutifs — vérifiez et rejouez depuis l'historique des livraisons.

FAQ

Quels événements mon compte peut-il recevoir ? Les comptes normaux reçoivent les cinq événements activity.*. user.register.v1 est réservé aux administrateurs, et webhook.test.v1 n'est que l'événement de test.

Comment vérifier qu'un webhook vient de SalesMind AI ? Recalculez la signature à partir du corps brut et de l'en-tête Webhook-Timestamp, puis comparez-la à l'en-tête Webhook-Signature. Voir « Vérifier la signature » ci-dessus.

Comment obtenir mon secret de signature ? L'enregistrement ne le renvoie pas. Appelez l'endpoint rotate-secret pour obtenir un nouveau secret, et mettez à jour votre copie stockée immédiatement.

Pourquoi mon endpoint a-t-il été suspendu ? SalesMind AI suspend un endpoint après trop de livraisons échouées d'affilée — 10 par défaut. Réparez votre serveur, puis réactivez l'endpoint.

Puis-je renvoyer un webhook que j'ai manqué ? Oui. Utilisez l'endpoint de rejeu pour renvoyer une livraison passée en tant que nouvel événement.

Mon URL a été acceptée mais aucun événement n'arrive. Pourquoi ? La vérification HTTPS et URL publique s'exécute au moment de la livraison, pas à l'enregistrement. Une URL incorrecte est acceptée au départ puis échoue à la livraison. Vérifiez votre historique des livraisons.