Webhook e trigger

Un Trigger è il modo in cui Letaido si accorge che è successo qualcosa in un'altra app, in tempo reale, senza dover continuare a controllare.

Quando un nuovo contatto arriva in HubSpot, quando qualcuno ti @menziona su Slack, quando un'opportunità cambia fase, Letaido lo scopre immediatamente e agisce.

Cosa puoi fare con questo

Le cose che i team configurano qui sono simili a:

• Quando un nuovo contatto HubSpot è MQL, valutalo rispetto al nostro ICP e pubblica il risultato in #mql-review.
• Quando qualcuno fa @mention del bot Slack in #pmm-questions, rispondi con il tono di voce del nostro brand.
• Quando un issue Linear viene etichettato come customer-facing, scrivi un riassunto pubblico di un paragrafo e invialo in DM al responsabile PMM.
• Quando viene pubblicato un release GitHub, crea automaticamente una bozza di email di lancio e inviala a Notion per la revisione.
• Quando termina un meeting Fathom, estrai gli action item e aggiungili a Linear.
• Quando uno scraper Apify termina, avvia la fase successiva della pipeline.

Descrivi il trigger e l'azione in un inglese semplice. L'agente di IA configura la connessione, chiede l'approvazione una volta, poi funziona in autonomia.

Come funziona dietro le quinte

Ci sono due versioni:

• Trigger dei connettori (preferiti). Un'iscrizione tipizzata a un servizio di terze parti. La configurazione richiede una sola chiamata. La piattaforma gestisce l'iscrizione, il signing secret, la logica di retry e la coda degli eventi. Gli eventi arrivano con uno schema noto (Slack, GitHub, Linear, HubSpot, Fathom, Apify e altri).
• Webhooks ad hoc. Per i servizi che non hanno ancora un Trigger del connettore integrato, l'agente crea un URL webhook generico, configura la terza parte per inviare POST a quell'URL e inserisce gli eventi nella stessa coda. Il costo è un po' più di lavoro di parsing, dato che lo schema è quello che la terza parte invia.

In ogni caso, l'agente sceglie quello giusto per te. Non scegli tu.

Come fluisce un evento

1. Il servizio di terze parti invia una richiesta POST a un URL pubblico di proprietà della piattaforma.
2. La piattaforma verifica la firma, analizza il payload, lo arricchisce (ad es. risolvendo gli ID dei canali in nomi per Slack) e lo inserisce in una coda interna.
3. Un consumer (un'app, un job o l'agente di chat) interroga la coda con un cursore nominato ed elabora gli eventi.
4. Ogni evento viene confermato dopo l'elaborazione; gli eventi non confermati vengono riconsegnati se il consumer si blocca.

I cursori sono per consumatore, quindi un'app Console e un job possono entrambi monitorare gli stessi eventi senza interferire l'uno con l'altro.

Affidabile vs conferma automatica

• Auto-ack (predefinito). Leggi gli eventi; spariscono dalla coda immediatamente. Semplice. Va bene per "seguire il feed, registrare in una tabella."
• Ack manuale. Leggi gli eventi, elaborali, poi conferma esplicitamente. Se l'elaborazione si interrompe, l'evento viene riconsegnato. Usa questo quando l'effetto collaterale (un'email, una scrittura nel database, una chiamata API downstream) non deve andare perso.

Se chiedi all'agente "un workflow affidabile", sceglie l'ack manuale per impostazione predefinita.

Forme comuni di richiesta

"Quando viene creato un nuovo contatto HubSpot con lifecycle stage = marketingqualifiedlead, valuta l'azienda rispetto al nostro ICP e pubblica il risultato su #mql-review."

L'agente: 1. Si iscrive al Trigger di creazione contatto di HubSpot. 2. Scrive un piccolo consumer (app Console o job) che recupera l'evento, chiama lo scorer ICP e pubblica su Slack tramite il connettore Slack. 3. Mostra sia l'approvazione della sottoscrizione HubSpot che l'approvazione Slack se è il primo utilizzo di queste superfici.

"Quando un issue di GitHub viene etichettato come pmm-review, redigi un riassunto di un paragrafo rivolto al cliente e inviamelo tramite DM."

"Quando qualcuno fa @mention del bot Slack in #pmm-questions, rispondi usando la skill della voce del brand."

Cosa vedi nell'area di lavoro

Per ogni sottoscrizione attiva: - Il connettore e il tipo di evento. - Lo stato del signing secret. - L'URL pubblico (per ad-hoc) o la configurazione dell'app di terze parti (per i trigger del connettore). - Il consumer che legge la coda.

Puoi mettere in pausa o revocare una sottoscrizione dall'interfaccia dell'Area di lavoro. La revoca restituisce 410 a qualsiasi POST in entrata successivo.

Limiti e casi limite

• Nessun evento è mai "fan-out dalla chat". I Trigger sono gestiti dal server. Se una sessione di chat viene chiusa, gli eventi continuano ad arrivare e si accumulano nella coda finché un consumer non li legge.
• La coda ha una finestra di conservazione. Gli eventi non letti più vecchi di alcuni giorni vengono eliminati. Se sospetti che un consumer fosse offline, controlla prima di presumere che un evento sia stato perso.
• I consumer dei siti pubblici hanno restrizioni aggiuntive. I Trigger della superficie del sito richiedono una revisione esplicita per ogni chiamata (nessuna approvazione generale), perché un flusso controllato dai visitatori rappresenta un rischio di costi per fan-out.
• I signing secret vengono memorizzati, mai visualizzati. L'agente può usarli ma non può leggerli.

Sotto il cofano. Gli eventi in entrata raggiungono nginx → api-proxy → connectors service. Il servizio verifica la firma confrontandola con il signing secret memorizzato, esegue l'hook di arricchimento del connector (ad es. il risolutore da user-ID a user-name di Slack), quindi scrive una riga in webhook_events. I consumer recuperano i dati tramite GET /webhooks/events?cursor=<name> con i parametri opzionali provider e ack. I consumer con ack manuale inviano una POST a /webhooks/ack con through_id.