Webhooks et déclencheurs

Un déclencheur est la façon dont Letaido remarque qu'un événement s'est produit dans une autre application, en temps réel, sans avoir à vérifier constamment.

Lorsqu'un nouveau contact arrive dans HubSpot, lorsque quelqu'un vous @mentionne sur Slack, lorsqu'une transaction change d'étape, Letaido le découvre immédiatement et agit.

Ce que vous pouvez faire avec ceci

Les éléments que les équipes configurent ici ressemblent à :

• Lorsqu'un nouveau contact HubSpot est MQL, évaluez-le par rapport à notre ICP et publiez le résultat dans #mql-review.
• Lorsque quelqu'un @mentionne le bot Slack dans #pmm-questions, répondez avec la voix de notre marque.
• Lorsqu'un ticket Linear est étiqueté customer-facing, rédigez un résumé public d'un paragraphe et envoyez-le par message privé au responsable PMM.
• Lorsqu'une version GitHub est publiée, rédigez automatiquement un e-mail de lancement et envoyez-le à Notion pour révision.
• Lorsqu'une réunion Fathom se termine, extrayez les éléments d'action et ajoutez-les à Linear.
• Lorsqu'un scraper Apify se termine, lancez l'étape suivante du pipeline.

Vous décrivez le déclencheur et l'action en langage simple. L'agent configure la connexion, demande votre approbation une fois, puis s'exécute de manière autonome.

Comment cela fonctionne en coulisses

Il existe deux versions :

• Déclencheurs de connecteur (recommandé). Un abonnement typé à un service tiers. La configuration se fait en un seul appel. La plateforme gère l'abonnement, le secret de signature, la logique de nouvelle tentative et la file d'attente des événements. Les événements arrivent avec un schéma connu (Slack, GitHub, Linear, HubSpot, Fathom, Apify, et autres).
• Webhooks ad hoc. Pour les services sans déclencheur de connecteur intégré, l'agent génère une URL de webhook générique, configure le tiers pour envoyer des requêtes POST vers celle-ci, et récupère les événements dans la même file d'attente. Le coût est un peu plus de travail d'analyse, puisque le schéma correspond à ce que le tiers envoie.

Dans tous les cas, l'agent choisit le bon pour vous. Vous ne choisissez pas.

Comment un événement circule

1. Le service tiers envoie une requête POST à une URL publique appartenant à la plateforme.
2. La plateforme vérifie la signature, analyse la charge utile, l'enrichit (par exemple en résolvant les identifiants de canaux en noms pour Slack) et la pousse dans une file d'attente interne.
3. Un consommateur (une application, une tâche ou l'agent de chat) interroge la file d'attente avec un curseur nommé et traite les événements.
4. Chaque événement est acquitté après traitement ; les événements non acquittés sont redistribués si le consommateur plante.

Les curseurs sont par consommateur, donc une application Console et une tâche peuvent toutes deux surveiller les mêmes événements sans se gêner mutuellement.

Fiable vs auto-ack

• Auto-ack (par défaut). Lit les événements ; ils disparaissent immédiatement de la file d'attente. Simple. Convient pour « suivre le flux, enregistrer dans une table ».
• Ack manuel. Lit les événements, les traite, puis les acquitte explicitement. Si le traitement plante, l'événement est redistribué. Utilisez cette option lorsque l'effet secondaire (un e-mail, une écriture en base de données, un appel API en aval) ne doit pas être perdu.

Si vous demandez à l'agent « un workflow fiable », il choisit l'acquittement manuel par défaut.

Formes courantes de demandes

« Lorsqu'un nouveau contact HubSpot est créé avec l'étape de cycle de vie = marketingqualifiedlead, évaluez l'entreprise par rapport à notre ICP et publiez le résultat dans #mql-review. »

L'agent : 1. S'abonne au déclencheur de création de contact HubSpot. 2. Écrit un petit consommateur (application Console ou tâche) qui récupère l'événement, appelle le scoreur ICP, publie sur Slack via le connecteur Slack. 3. Présente à la fois l'approbation de l'abonnement HubSpot et l'approbation Slack s'il s'agit de la première utilisation de ces surfaces.

« Lorsqu'un ticket GitHub est étiqueté pmm-review, rédigez un résumé d'un paragraphe destiné aux clients et envoyez-le-moi par message privé. »

« Lorsque quelqu'un @mentionne le bot Slack dans #pmm-questions, répondez en utilisant la compétence de voix de marque. »

Ce que vous voyez dans l'espace de travail

Pour chaque abonnement actif : - Le connecteur et le type d'événement. - Le statut du secret de signature. - L'URL publique (pour ad-hoc) ou la configuration de l'application tierce (pour les déclencheurs de connecteur). - Le consommateur qui lit la file d'attente.

Vous pouvez mettre en pause ou révoquer un abonnement depuis l'interface de l'espace de travail. La révocation renvoie un code 410 à tous les POSTs entrants ultérieurs.

Limites et cas particuliers

• Aucun événement n'est jamais "diffusé depuis le chat." Les déclencheurs sont pilotés par le serveur. Si une session de chat est fermée, les événements continuent d'arriver et s'accumulent dans la file d'attente jusqu'à ce qu'un consommateur les lise.
• La file d'attente a une fenêtre de rétention. Les événements non lus datant de plus de quelques jours sont supprimés. Si vous soupçonnez qu'un consommateur était hors ligne, vérifiez avant de supposer qu'un événement a été manqué.
• Les consommateurs de site public sont soumis à des restrictions supplémentaires. Les déclencheurs de surface de site nécessitent un examen explicite par appel (pas d'approbation globale), car un flux contrôlé par le visiteur présente un risque de coût de diffusion.
• Les secrets de signature sont stockés, jamais affichés. L'agent peut les utiliser mais ne peut pas les relire.

Sous le capot. Les événements entrants passent par nginx → api-proxy → service de connecteurs. Le service vérifie la signature par rapport au secret de signature stocké, exécute le hook d'enrichissement du connecteur (par exemple, le résolveur d'ID utilisateur vers nom d'utilisateur de Slack), puis écrit une ligne dans webhook_events. Les consommateurs récupèrent via GET /webhooks/events?cursor=<name> avec les paramètres optionnels provider et ack. Les consommateurs avec accusé de réception manuel envoient une requête POST à /webhooks/ack avec through_id.