QuantumOutbound peut envoyer des données d'événements à votre serveur dès que quelque chose se produit — une demande de connexion est envoyée, un prospect accepte, un message est envoyé ou reçu, ou une conversation est taguée. Au lieu d'interroger l'API en permanence, votre endpoint reçoit une requête POST avec tout le contexte.
Ce guide vous montre comment configurer un endpoint webhook, choisir les événements qui vous intéressent et traiter le payload.
Prérequis
- Un compte QuantumOutbound avec au moins un expéditeur actif
- Un endpoint HTTPS accessible publiquement pouvant recevoir des requêtes POST
Comment fonctionnent les webhooks
QuantumOutbound déclenche un webhook chaque fois qu'un événement pertinent se produit sur un fil de conversation dans votre boîte de réception — qu'il soit déclenché par une action de campagne ou par une modification manuelle que vous effectuez 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 automatisés 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 supprimé sur un fil de conversation |
Configurer votre endpoint webhook
- Dans la barre latérale gauche, cliquez sur l'icône Paramètres (engrenage) en bas.
- Cliquez sur Webhooks.
- Collez l'URL de votre endpoint HTTPS.
- Choisissez les types d'événements que vous souhaitez recevoir.
- Sélectionnez les agents dont vous voulez recevoir les événements.
- Cliquez sur Enregistrer.
💡 Astuce : Utilisez le bouton Test pour envoyer un payload d'exemple à votre endpoint. Cela confirme que votre serveur peut recevoir des requêtes avant que de vrais événements ne se déclenchent.
Comprendre le payload
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 unique de livraison (utilisé comme clé d'idempotence) | df313559-7cb1-... |
type | Le type d'événement | activity.connection.accepted.v1 |
timestamp | Date et heure de l'événement (ISO 8601) | 2026-02-06T05:05:36+01:00 |
L'objet data contient ces sections :
| Section | Ce qu'elle contient |
|---|---|
data.agent | Nom de votre agent, détails de l'entreprise, services, ton de marque et 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 (ex. invitation_send), détails de la dernière activité et indicateur de terminaison |
data.threadBox | Noms complets de l'expéditeur et du contact, tableau de tags, statut de la conversation, score de compatibilité, raisonnement IA, nom du persona et statut de réponse |
data.sender | Profil LinkedIn complet du compte expéditeur, infos du contact dans la base de connaissances et analyse de personnalité MBTI |
data.contact | Profil LinkedIn du prospect, titre, résumé, localisation, compétences, entreprises actuelles et analyse MBTI |
data.messages | Tableau des messages dans le fil de conversation |
En-têtes de sécurité inclus avec chaque livraison :
| En-tête | Description |
|---|---|
webhook-signature | Signature HMAC pour vérifier que la requête provient de QuantumOutbound |
webhook-timestamp | Horodatage Unix du moment où le payload a été envoyé |
webhook-idempotency-key | Clé unique pour éviter le traitement de livraisons en double |
webhook-key-id | Identifie la clé de signature utilisée |
💡 Astuce : Le payload complet est volumineux et inclut tout le contexte de l'agent. Envoyez d'abord un webhook de test à votre endpoint, puis utilisez ce JSON pour ne mapper que les champs dont vous avez besoin dans votre handler.
Consulter l'historique des livraisons
Vous pouvez vérifier si un webhook a été 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.
Erreurs courantes
« Le test fonctionne mais les vrais événements ne se déclenchent pas »
Assurez-vous d'avoir une campagne active avec des prospects qui progressent dans le workflow. Les webhooks se déclenchent lorsque le système effectue une action (envoie une invitation, envoie un message, reçoit une réponse, tague un fil) ou lorsque vous modifiez manuellement un tag. Si aucune activité n'est en cours, il n'y a pas d'événements à envoyer.
« Je reçois des événements mais il manque des champs dans le payload »
Le payload varie légèrement selon le type d'événement. Un événement activity.invitation.sent.v1 n'aura pas les champs liés aux réponses, par exemple. Vérifiez le payload de test pour votre type d'événement spécifique pour voir quels champs sont inclus.
« Le payload est très volumineux »
C'est normal. Chaque livraison inclut tout le contexte de l'agent (services, playbook commercial, ton de marque) afin que votre handler dispose de tout le nécessaire pour router et traiter l'événement. Parsez uniquement les champs dont vous avez besoin.
Points clés à retenir
- Les webhooks envoient des données en temps réel à votre serveur lorsque des événements se produisent — actions automatisées de campagne et modifications manuelles.
- Cinq types d'événements couvrent l'ensemble du cycle de prospection : invitation envoyée, connexion acceptée, message envoyé, message reçu et tag mis à jour.
- Le payload inclut le contexte complet de l'agent, de la campagne et du contact dans une structure JSON imbriquée.
- Les en-têtes de sécurité vous permettent de vérifier que chaque livraison provient de QuantumOutbound.
- Commencez par un webhook de test pour capturer la structure complète du payload avant de développer votre handler.