Webhook #

I webhook consentono a Your AI Connector di notificare automaticamente gli altri strumenti aziendali ogni volta che accade qualcosa di importante: la creazione di un nuovo contatto, la prenotazione di un appuntamento, la ricezione di un messaggio. Invece di controllare manualmente gli aggiornamenti, i sistemi connessi ricevono una notifica istantanea nel momento in cui si verifica un evento.

Cosa sono i webhook? #

Pensa a un webhook come a un messaggio di testo automatico tra due app. Quando accade qualcosa in Your AI Connector (come l’iscrizione di un nuovo contatto), la piattaforma invia istantaneamente una notifica a un altro sistema a tua scelta. Devi fornire un indirizzo web (chiamato “URL del webhook”) a cui inviare queste notifiche; solitamente questo viene fornito dal tuo CRM, dalla piattaforma di automazione o dallo sviluppatore.

I webhook inviano dati solo IN USCITA da Your AI Connector. Un webhook è una strada a senso unico da Your AI Connector verso i tuoi altri strumenti. Non esiste un URL webhook che invii lead, contatti o messaggi ALL’INTERNO della piattaforma. Per inserire un nuovo lead — da un modulo web, dal tuo CRM o da GoHighLevel — il tuo sistema effettua invece una chiamata API. Consulta Accesso API (l’operazione Crea un contatto) e Funnel. L’unica cosa di cui hai bisogno per la direzione in entrata è la tua chiave API, che si trova nella sua sezione dedicata: consulta Accesso API. La pagina Webhook descritta qui è esclusivamente per la direzione in uscita.

Gli utilizzi comuni includono:

• Sincronizzazione dei nuovi contatti con il tuo CRM.
• Attivazione di un flusso di lavoro in Zapier, Make o Pabbly quando viene applicato un tag.
• Notifica al tuo team su Slack quando viene richiesto l’intervento umano.
• Aggiornamento del sistema di calendario quando viene prenotato un appuntamento.
• Registrazione dei riepiloghi delle conversazioni nel tuo database.

Configurazione dei webhook #

1. Nella barra laterale sinistra, fai clic su Impostazioni (icona a forma di ingranaggio).
2. Nella barra laterale Impostazioni, sotto il gruppo Integrazioni, fai clic su Webhook.

Su un account in cui non sono ancora stati configurati webhook, la pagina si presenta così:

3. Fai clic su New webhook in alto a destra. Si aprirà un modulo direttamente nella pagina:

4. Compila:
   • URL dell’endpoint — l’indirizzo web a cui Your AI Connector invierà le notifiche degli eventi. Lo ottieni dal tuo sistema esterno (CRM, piattaforma di automazione o server personalizzato).
   • Nome — un’etichetta che riconoscerai in seguito (ad es. “Avvisi Slack” o “Sincronizzazione CRM”). Solo per tuo riferimento.

Il tuo URL del webhook deve essere un indirizzo https:// raggiungibile pubblicamente. Gli indirizzi http:// semplici, localhost o gli indirizzi di rete privata e quelli interni alla piattaforma vengono rifiutati al momento del salvataggio. Per testare dal tuo computer, usa un tunnel pubblico (webhook.site o ngrok) invece di localhost.

5. In Eventi, fai clic sugli eventi che vuoi che questo webhook riceva: tutti i 22 sono elencati in I 22 eventi webhook.
6. (Facoltativo) Attiva Riprova consegne non riuscite se vuoi che Your AI Connector continui a tentare in caso di errore temporaneo; vedi Riprovare le consegne non riuscite.
7. Fai clic su Crea webhook. Apparirà nell’elenco sotto il modulo e potrai fare clic su Test sulla sua riga in qualsiasi momento per inviare un payload di esempio al tuo endpoint.

Autorizzazione necessaria. L’aggiunta, la modifica o il test dei webhook richiedono l’autorizzazione “modifica” per le Integrazioni (i membri del team con sola visualizzazione vedranno un avviso di sola lettura invece del modulo).

La firma di un webhook richiede che sia già stato salvato: apri la riga di un webhook esistente per modificarlo e il pannello Segreto di firma apparirà in fondo al modulo di modifica. Una bozza nuova di zecca non salvata non ha ancora l’opzione di firma; vedi Payload firmati qui sotto.

Un webhook per tutti i tuoi account cliente (Agenzie) #

Se gestisci un’agenzia, non devi ricreare lo stesso webhook su ogni account cliente. Nell’account agenzia, il modulo webhook presenta un interruttore aggiuntivo: Attiva anche per tutti gli account cliente. Attivalo e questo webhook riceverà anche gli eventi che si verificano su ogni account cliente sotto la tua agenzia: un unico endpoint per l’intera agenzia.

Come funziona:

• Il blocco user ti indica a quale cliente appartiene un evento. Ogni notifica contiene già un blocco user che identifica l’account in cui si è verificato l’evento, in modo che la tua automazione possa instradare i dati per cliente.
• Le impostazioni del tuo webhook si applicano ovunque. Gli eventi selezionati, il segreto di firma e l’impostazione di riprova vengono utilizzati anche per le consegne agli account cliente.
• Nessuna doppia consegna. Se un account cliente ha un proprio webhook che punta allo stesso URL, quello verrà utilizzato per gli eventi di quell’account: lo stesso evento non arriverà mai due volte allo stesso endpoint.
• I clienti non lo vedono. Il webhook non appare nella pagina Webhook dell’account cliente e i clienti non possono disattivarlo: spetta a te gestirlo.
• L’affidabilità è monitorata per singolo account cliente. Se il tuo endpoint continua a fallire, viene disattivato automaticamente solo per l’account le cui consegne non sono andate a buon fine (vedi Affidabilità dei webhook), non per l’intera agenzia contemporaneamente.

L’interruttore appare solo negli account agenzia. È supportata anche l’impostazione tramite API: vedi il campo apply_to_sub_accounts nelle API Webhook.

Eventi trigger disponibili #

Puoi abilitare o disabilitare ciascuno dei 22 eventi webhook in modo indipendente. Quando si verifica un evento, Your AI Connector invia una notifica al tuo URL webhook con i dati pertinenti. Ogni evento, il suo significato e il codice event che inserisce nel payload sono elencati insieme in I 22 eventi webhook più avanti in questa pagina.

Buono a sapersi: Attività creata, Attività aggiornata e Attività completata sono completamente selezionabili e vengono salvate correttamente. Anche Riepilogo giornaliero creato è una recente aggiunta. Vedi Webhook Attività completata di seguito per la struttura di quel payload.

Trigger webhook basati su tag #

subscribed_to_tags non limita gli eventi di un webhook a un tag. Limita solo quali tag producono una notifica di riepilogo della conversazione. Per ricevere una richiesta quando viene applicato un tag specifico, imposta un URL webhook su quel tag nella scheda Tag dell’agente (o della campagna).

Il modulo webhook stesso non ha un selettore di tag, né durante la creazione di un nuovo webhook né durante la modifica di uno esistente, quindi subscribed_to_tags può essere letto o modificato solo tramite l’API Webhook o chiedendo assistenza.

Buono a sapersi: la modifica di un webhook esistente che ha un elenco subscribed_to_tags (rinominarlo, modificarne gli eventi, attivare/disattivare i tentativi) non cancella più tale elenco: poiché il modulo non ha un selettore di tag da inviare, il salvataggio da questa pagina ora lascia l’elenco esistente intatto. (Questo era un vero bug prima del 21 luglio 2026: il salvataggio dal modulo webhook cancellava l’elenco perché inviava sempre un elenco di tag vuoto. Se un webhook ha perso il suo elenco subscribed_to_tags prima di quella data, dovrà essere riconfigurato tramite l’API.)

Genera riepilogo per i contatti con tag #

Laddove un webhook ha un elenco subscribed_to_tags, puoi attivare Genera riepilogo. Quando abilitato, Your AI Connector genera automaticamente un riepilogo della conversazione per il contatto quando uno di quei tag viene applicato e lo include nei dati del webhook: contesto completo senza una richiesta separata.

Test del webhook #

1. Apri Impostazioni → Integrazioni → Webhook.
2. Nella riga del tuo webhook, fai clic su Test.
3. Controlla il tuo sistema esterno per confermare che abbia ricevuto i dati di test.
4. Esamina il formato dei dati per assicurarti che il tuo sistema possa analizzarli correttamente.

Per un test completo end-to-end, invia un messaggio che attiverebbe uno dei tuoi eventi configurati (una trasmissione o un messaggio in arrivo su un canale connesso) e verifica che il webhook venga attivato con i dati reali.

Cosa costituisce una consegna riuscita #

Che tu faccia clic su Test o che l’evento si attivi realmente, inviamo la stessa cosa:

• Una richiesta POST (mai GET), con il corpo come JSON e Content-Type: application/json.
• Le intestazioni elencate in Payload firmati. Le intestazioni di firma sono incluse solo dopo aver impostato un segreto di firma.

Consideriamo la consegna riuscita quando:

• Il tuo endpoint risponde con qualsiasi stato 2xx (200, 201, 204: vanno tutti bene).
• Risponde entro 30 secondi.

Alcune cose che sorprendono:

• Il corpo della risposta viene ignorato. Non è necessario restituire alcun JSON particolare. Un 200 vuoto è sufficiente.
• I reindirizzamenti contano come errore. Non li seguiamo, quindi un 301 o 302 (incluso un reindirizzamento con barra finale, o da http a https) viene registrato come consegna fallita. Salva l’URL finale, non uno che reindirizza.
• Le stringhe di query sono pienamente supportate. https://your-app.com/hook?token=abc123 viene inviato esattamente come lo hai salvato, quindi inserire un token nella stringa di query funziona tanto bene quanto inserirlo nel percorso.
• Il tuo URL deve essere https:// e raggiungibile pubblicamente. Gli indirizzi che appartengono all’infrastruttura di Your AI Connector vengono rifiutati, ma i tuoi endpoint su Google Cloud Functions, Cloud Run, App Engine, Firebase Hosting o ovunque altro vanno bene.
• Un firewall o un livello di protezione dai bot davanti al tuo endpoint può bloccarci. Il caso più comune è Cloudflare: se la tua zona ha la modalità “Bot Fight Mode” o una sfida gestita attiva, la nostra richiesta riceve una pagina di sfida “Just a moment…” con un 403 invece di raggiungere il tuo server — e una richiesta server-to-server non può mai superare una sfida del browser, quindi sia il pulsante Test che gli eventi reali falliscono allo stesso modo. Il pulsante Test ti dirà quando ciò accade (“Cloudflare sta mostrando una sfida bot alla nostra richiesta”). Risolvi il problema in Cloudflare con una regola di Sicurezza / WAF che ignora le sfide per il tuo percorso webhook (o per l’user agent Webhook-Delivery/1.0), quindi clicca di nuovo su Test.
• Se il tuo firewall necessita invece di una whitelist di IP (ad esempio il piano gratuito di Cloudflare, dove la semplice modalità Bot Fight Mode non può essere ignorata da una regola WAF, ma una regola di accesso IP impostata su Consenti viene eseguita prima), possiamo aiutarti: ogni consegna, sia dal pulsante Test che da un evento live, viene inviata da un indirizzo IPv4 fisso (nessun intervallo, nessun IPv6, nessuna rotazione). Contatta l’assistenza e ti forniremo l’indirizzo da inserire nella whitelist. Mantieni la verifica della firma come tuo controllo di attendibilità effettivo, poiché convalida ogni payload indipendentemente dalla sua provenienza.
• Il risultato del Test ti dice esattamente cosa ha risposto il tuo endpoint. Un test fallito ora mostra il motivo reale (lo stato HTTP restituito dal tuo endpoint, un timeout, o che non siamo riusciti affatto a raggiungere l’indirizzo) invece di un errore generico, e un test su un webhook salvato viene inviato firmato quando la firma è attiva, esattamente come un evento live.

Utilizzo di n8n, Make o Zapier (“Test URL” vs “Production URL”) #

Le piattaforme di automazione solitamente forniscono due diversi indirizzi webhook, il che spesso crea confusione:

• Un URL di test (in n8n contiene /webhook-test/). Questo riceve dati solo mentre stai osservando attivamente l’area di lavoro e hai appena fatto clic su Listen for test event (o Test workflow). Cattura un singolo evento e poi smette di ascoltare; quindi, fare clic su Test in Your AI Connector più volte di seguito cattura solo il primo, e solo se la finestra di ascolto è attiva in quel preciso momento. Per testare: fai prima clic su Listen for test event in n8n, poi torna a Your AI Connector e fai clic su Test una volta.
• Un URL di produzione (in n8n contiene /webhook/, senza -test). Questo è quello da incollare in Your AI Connector per gli eventi dal vivo. Funziona solo una volta che il tuo flusso di lavoro è impostato su Active. Se il flusso di lavoro non è attivo, n8n rifiuta la richiesta con un errore “404 / webhook not registered”, anche se Your AI Connector ha inviato i dati correttamente.

In breve: testa con l’URL di test mentre sei in ascolto, ma affinché il webhook continui a funzionare con i contatti reali, salva l’URL di produzione in Your AI Connector e assicurati che il workflow sia Active.

Formato dati webhook #

Quando un webhook viene attivato, Your AI Connector invia dati strutturati (JSON) al tuo URL del webhook. Se utilizzi una piattaforma di automazione come Zapier o Make, questi dati vengono analizzati automaticamente. Se stai creando un’integrazione personalizzata:

{
  "event": "contactCreated",
  "contact": { "id": "<contact-id>", "first_name": "Jane", "...": "..." },
  "campaign": { "id": "<campaign-id>", "name": "AI Receptionist", "status": "Live" },
  "agent": { "id": "<agent-id>", "name": "Front Desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" }
}

campaign o agent — solitamente uno, non entrambi. Se il tuo account utilizza gli agenti, i tuoi contatti sono assegnati a un agente anziché a una campagna, quindi campaign arriva come null e agent ti indica chi l’ha gestito. Gli account più vecchi basati su campagne vedono l’inverso. Leggi quello che è compilato; non dare per scontato che campaign sia sempre presente.

Il blocco agent è arrivato il 15 agosto 2026. Si affianca a campaign negli eventi legati a una conversazione — una chat conclusa, non disturbare, una ripresa, un annullamento dell’archiviazione, una pausa dell’IA, un nuovo messaggio, un riepilogo della conversazione e il webhook che puoi impostare su un tag — e contiene id e name dell’agente che gestisce la conversazione, oppure null quando non è coinvolto alcun agente. È puramente aggiuntivo: ogni campo che ricevi già rimane invariato, quindi un ricevitore creato prima di tale data continuerà a funzionare senza bisogno di aggiornamenti.

Alcuni eventi aggiungono il proprio blocco di primo livello. Ad esempio, Appointment Booked aggiunge un blocco appointment (vedi Webhook Appointment Booked), New Message aggiunge un blocco message completo con il testo (vedi Webhook New Message), mentre Deliveries e Reads aggiungono un breve blocco message contenente solo l’ID e lo stato del messaggio (vedi Webhook Deliveries and Reads).

Deliveries e Reads indicano a quale messaggio si riferiscono, ma non il contenuto. Contengono un blocco message con l’ id e lo status del messaggio — e quell’ id è lo stesso messageId restituito dall’endpoint di invio messaggi, così puoi associare una conferma di consegna o di lettura all’esatto messaggio inviato — ma non il corpo del messaggio. Replies non contiene alcun blocco message. Se ti servono le parole inviate o ricevute, iscriviti anche a New Message.

Due cose da sapere prima di scrivere il tuo ricevitore. Non c’è alcun campo timestamp e nessun wrapper data. Ogni blocco si trova al livello principale dell’oggetto JSON, come mostrato sopra.

I 22 eventi webhook #

I 22 eventi webhook, con l’etichetta visualizzata che selezioni nell’app e il codice event inviato nel payload. Il codice event è una breve stringa che non corrisponde all’etichetta visualizzata, quindi fai corrispondere il tuo ricevitore al codice, non all’etichetta:

Altri due codici non appaiono mai in quell’elenco perché non vi sei iscritto: contact_tags_updated, inviato da un URL webhook impostato su un singolo tag, e summary_generated, inviato quando viene scritto un riepilogo della chat per un tag nell’elenco subscribed_to_tags di un webhook.

Canale connesso non è ancora inviato. Appare nell’elenco degli eventi, ma al momento nulla lo emette. Non basare alcuno sviluppo su di esso.

Le notifiche basate su tag e attività utilizzano le proprie strutture separate. Vedi Tag contatto aggiornati e Attività completata.

Webhook di creazione contatto #

Inviato quando viene attivato l’evento Contatto creato (un nuovo contatto viene aggiunto manualmente, tramite importazione o tramite API).

Nome evento #

contactCreated

Formato del payload #

{
  "event": "contactCreated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

Il campione “Test” e un evento reale hanno un aspetto leggermente diverso. Il pulsante di test invia dati segnaposto (John Doe, una campagna di esempio). Un evento reale di contatto creato contiene i dettagli effettivi del contatto e alcuni campi potrebbero essere vuoti a seconda del canale.

Webhook Nuovo messaggio #

Questo webhook si attiva ogni volta che un messaggio viene aggiunto a una conversazione, su qualsiasi canale. Copre entrambe le direzioni: i messaggi che il contatto ti invia e i messaggi che la tua IA, il tuo team o una campagna inviano al contatto. È l’unico webhook che include il testo del messaggio, quindi è quello da utilizzare quando desideri replicare le conversazioni in un sistema esterno.

Nome evento #

new_message

Formato del payload #

{
  "event": "new_message",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "body": "Hi, are you open on Saturday?",
    "direction": "inbound",
    "status": "received",
    "created_at": "2026-07-30T17:27:06.000Z",
    "channel": "whatsapp_web"
  }
}

Non c’è ancora alcun blocco campaign in questo payload. New Message invia contact, agent, user e message. Il blocco agent è stato aggiunto il 15 agosto 2026 e ti indica quale agente gestisce la conversazione; se hai bisogno anche del contesto della campagna, cerca il contatto tramite l’API usando contact.id.

I record interni dell’IA non attivano questo webhook. Oltre ai messaggi reali, la piattaforma mantiene le proprie righe di contabilità in una conversazione (le chiamate agli strumenti dell’IA e i record dei turni interni). Questi non vengono mai inviati: riceverai solo i messaggi che sono stati effettivamente inviati o ricevuti.

Webhook Deliveries and Reads #

Questi due eventi riportano cosa è successo a un messaggio dopo che ha lasciato Your AI Connector: Deliveries si attiva quando un messaggio raggiunge il contatto (o fallisce nel farlo), e Reads si attiva quando il contatto lo apre, sui canali che supportano le conferme di lettura.

Entrambi contengono un blocco message con l’ID del messaggio a cui si riferisce l’evento, così puoi associare l’aggiornamento all’esatto messaggio che hai inviato.

Nomi degli eventi #

delivered e undelivered per Deliveries, read per Reads.

Formato del payload #

{
  "event": "delivered",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "ad_referral": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "status": "delivered"
  }
}

Come associare un aggiornamento al messaggio inviato. Memorizza l’ messageId che ricevi quando invii un messaggio tramite l’API. Quando arriva una notifica di Deliveries o Reads, cerca quell’ID memorizzato rispetto a message.id nel payload — quella è la tua conferma di consegna o di lettura per quell’esatto messaggio.

Qui non c’è il testo del messaggio. Il blocco message contiene solo l’ID e lo stato. Iscriviti a New Message se ti serve anche il corpo del messaggio.

Il blocco message è presente solo quando sappiamo di quale messaggio si tratta. Nel raro caso di un aggiornamento che non possiamo collegare a un messaggio memorizzato, il blocco viene omesso del tutto invece di essere inviato vuoto — quindi verifica che message esista prima di leggere message.id.

Una notifica per ogni cambio di stato. Un singolo messaggio in uscita normalmente produce una notifica delivered e poi, sui canali con conferme di lettura, una read. Un invio fallito produce invece undelivered.

Webhook Appuntamento prenotato #

Si attiva quando un contatto prenota un appuntamento. Si attiva allo stesso modo sia che l’AI lo abbia prenotato durante una conversazione, che tu lo abbia prenotato a mano o che sia arrivato tramite l’API.

Nome evento #

booked

Formato del payload #

{
  "event": "booked",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com"
  },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z",
    "status": "confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": null,
    "event": {
      "id": "<service-id>",
      "event_name": "Intro Call",
      "slot_duration": 30,
      "location": "Zoom",
      "meeting_link": "https://...",
      "event_type": "online"
    }
  }
}

google_calendar_event_id è spesso null in questo webhook, ed è normale. L’evento di Google Calendar viene creato nello stesso momento in cui viene inviata questa notifica, quindi l’ID solitamente non è ancora pronto. Recupera l’appuntamento tramite il suo appointment_id un momento dopo se ne hai bisogno. Rimane null in modo permanente se l’account non ha un Google Calendar collegato, quindi non aspettarlo all’infinito.

Il pulsante “Test” non include il blocco appointment. Usalo per confermare che il tuo endpoint risponda, quindi effettua una prenotazione reale per vedere il payload completo.

Due casi in cui questo webhook non viene attivato: appuntamenti importati da un calendario esterno e prenotazioni che arrivano tramite l’integrazione Formitable.

Webhook di aggiornamento dei tag del contatto #

Si attiva quando un tag viene applicato a un contatto e tale tag ha un URL webhook configurato sull’agente o sulla campagna a cui appartiene il contatto.

Nome evento #

contact_tags_updated

Quando viene attivato #

• Un tag viene applicato a un contatto a cui è assegnato un agente, una campagna o entrambi.
• Almeno uno dei tag applicati ha un URL webhook impostato nella scheda Tag di quell’agente o campagna.

Se il contatto li ha entrambi e i tag della campagna contengono URL webhook, questi hanno la priorità; altrimenti vengono utilizzati quelli dell’agente.

Se nello stesso aggiornamento vengono applicati più tag con URL webhook diversi, viene inviata una richiesta per ogni URL, contenente solo i tag associati a quell’URL.

La rimozione di un tag non invia mai una richiesta. La maggior parte degli utenti punta questi URL a un’azione (riscuotere un deposito, prenotare uno slot, avvisare un rappresentante), quindi la rimozione di un tag da un contatto veniva utilizzata per rieseguire quell’azione. Ora non è più possibile. Una rimozione viene comunque visualizzata in removed_tags quando avviene nello stesso aggiornamento di un’applicazione che punta allo stesso URL, in modo che un’automazione che legge entrambi gli array mantenga il quadro completo; ciò che non vedrà mai è una richiesta causata dalla sola rimozione. (Modificato il 12 agosto 2026. Prima di tale data, anche le rimozioni inviavano una richiesta.)

Formato del payload #

{
  "event": "contact_tags_updated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "is_bot_active": true,
    "ad_referral": {
      "ctwa_clid": "ARAbc123...",
      "source_id": "120210000000000",
      "source_type": "ad",
      "source_url": "https://fb.me/xxxx",
      "headline": "Get 20% off today",
      "body": "Message us now to claim your discount",
      "channel": "whatsapp"
    }
  },
  "added_tags": ["qualified-lead"],
  "removed_tags": ["new-lead"],
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

Test di un webhook di tag #

Accanto al campo dell’URL del webhook nella scheda Tag è presente un pulsante Test. Invia immediatamente un payload di esempio a quell’URL, in modo da poter confermare che la tua automazione lo riceva prima di attendere una conversazione reale.

Il test invia la stessa forma contact_tags_updated mostrata sopra, utilizzando un contatto segnaposto, con il tag che stai testando in added_tags e un removed_tags vuoto. Ciò che la tua automazione vede nel test è ciò che vedrà in produzione.

Due cose da sapere:

• Salva prima il tag. Il test cerca il tag in base al suo nome salvato, quindi un tag nuovo di zecca o una ridenominazione non salvata non possono ancora essere testati. Il pulsante rimane disattivato finché il nome sullo schermo non corrisponde a quello salvato.
• Un test fallito non conta contro il tuo webhook. I test non contribuiscono mai allo spegnimento automatico dopo ripetuti fallimenti descritto in Affidabilità webhook.

Se il test fallisce, il messaggio ti indica cosa ha risposto il tuo endpoint (ad esempio un 404 o un 500), il che è solitamente sufficiente per individuare un URL errato o un flusso di lavoro che non è attivo.

Webhook di completamento attività #

Solo per riferimento. I webhook delle attività (come dati) sono documentati qui per gli sviluppatori; gli eventi Attività creata, Attività aggiornata e Attività completata sono selezionabili nell’elenco standard degli eventi nel modulo webhook come qualsiasi altro evento: vedi Eventi trigger disponibili e I 22 eventi webhook.

Questo payload viene inviato quando un’attività passa a una fase contrassegnata come fase di completamento. Un’attività che si sposta tra fasi non di completamento invia invece il formato taskUpdated.

Nome evento #

taskCompleted

Quando viene attivato #

• Un’attività viene aggiornata.
• Il suo valore stage è cambiato rispetto al valore precedente.
• La nuova fase è configurata come fase di completamento nelle impostazioni delle fasi attività dell’account.

Formato del payload #

{
  "event": "taskCompleted",
  "contact": {
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<task-id>",
    "title": "Follow up with Jane",
    "description": "Confirm pricing and send proposal",
    "type": "follow_up",
    "priority": "high",
    "stage": "<stage-id>",
    "due_date": "2026-01-20T15:00:00Z",
    "source": "ai",
    "source_detail": "<source-detail>",
    "campaign_id": "<campaign-id>",
    "linked_human_alert": "<human-alert-id>",
    "tags": ["qualified-lead"],
    "notes": "Customer requested a callback"
  }
}

Disattivare (o eliminare) un webhook #

Ogni webhook ha un interruttore on/off, proprio sulla sua riga. Spegnerlo (off) impedisce la ricezione di eventi, ma mantiene tutto ciò che hai configurato: l’URL, gli eventi, qualsiasi segreto di firma. Riaccendilo e riprenderà da dove era rimasto; nulla di ciò che è accaduto mentre era spento verrà consegnato in seguito.

Utilizza questa funzione quando desideri sospendere temporaneamente le consegne: ad esempio, se il tuo endpoint è in fase di ricostruzione, se stai eseguendo il debug di un’integrazione troppo rumorosa o se stai mettendo in pausa un’automazione.

Eliminare un webhook (l’icona del cestino sulla sua riga) lo rimuove definitivamente, incluso il suo segreto di firma. Se vuoi solo interrompere le consegne, spegnilo invece: l’eliminazione serve quando hai finito completamente con l’endpoint.

Questo non è lo stesso che disattivare automaticamente un webhook. Se disabilitiamo il tuo webhook dopo ripetuti errori (vedi Affidabilità dei Webhook), l’interruttore qui sopra non lo riattiverà. Una volta corretto l’endpoint, modifica il webhook e salvalo con un URL diverso (qualsiasi modifica all’URL lo riabilita), oppure chiama l’endpoint di riabilitazione tramite API, o chiedi al supporto e lo riattiveremo noi per te.

Payload firmati (Verifica che un webhook provenga realmente da noi) #

Chiunque conosca il tuo URL webhook potrebbe inviargli una richiesta falsa. Se agisci automaticamente sui webhook — aggiornando la fatturazione, creando record CRM — attivare la firma ti consente di verificare che ogni richiesta provenga effettivamente da noi.

La firma è opzionale e disattivata per impostazione predefinita, e si attiva per ogni webhook, dalla vista di modifica di quel webhook (apri la riga di un webhook salvato).

Attivazione della firma #

1. Apri il webhook (Impostazioni → Integrazioni → Webhook → clicca sulla riga del tuo webhook).
2. Nella sezione Segreto di firma, clicca su Genera.
3. Copia il segreto (inizia con whsec_) e salvalo nel tuo sistema ricevente. Trattalo come una password.

Puoi tornare a visualizzare, copiare, ruotare o disattivare il segreto in qualsiasi momento dallo stesso pannello.

Cosa inviamo #

Una volta attivata la firma, ogni consegna per quel webhook contiene questi due header HTTP aggiuntivi:

Questi tre sono presenti su ogni consegna, firmata o meno:

Come verificare #

La firma è un HMAC-SHA256 della stringa <timestamp>.<raw request body>, utilizzando il tuo segreto di firma come chiave.

Verifica rispetto al corpo della richiesta grezza: i byte esatti che hai ricevuto. Se il tuo framework analizza il JSON e lo ri-serializza prima del controllo, i byte possono cambiare e la firma non corrisponderà.

Esempio in Node.js:

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"]; // "v1=<hex>"

  // Reject anything older than 5 minutes so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature.replace("v1=", "")), Buffer.from(expected));
}

Esempio in Python:

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    signature = headers["X-Webhook-Signature"].replace("v1=", "")

    # Reject anything older than 5 minutes so a captured request can't be replayed later.
    if abs(time.time() - int(timestamp)) > 300:
        return False

    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()

    return hmac.compare_digest(signature, expected)

Confronta le firme con una funzione a tempo costante (timingSafeEqual / compare_digest), non con ==. Non ha alcun costo e previene una sottile classe di attacchi.

Rotazione del segreto #

Fai clic su Ruota per sostituire il segreto. Il passaggio è immediato: la consegna successiva viene firmata esclusivamente con il nuovo segreto. Se il tuo endpoint è attivo, accetta sia il vecchio che il nuovo segreto per alcuni minuti mentre distribuisci quello nuovo.

Disattivare la firma interrompe semplicemente l’invio delle intestazioni di firma.

Riprovare le consegne fallite #

Per impostazione predefinita, una consegna che fallisce non viene riprovata: se il tuo sistema è inattivo in quel momento, l’evento andrà perso.

Attiva Riprova consegne fallite su un webhook (nel modulo di creazione/modifica) e continueremo a riprovare:

Ciò copre circa 2 ore e 40 minuti, quindi un webhook può sopravvivere a una finestra di manutenzione o a una breve interruzione da parte tua.

Cosa viene riprovato: problemi temporanei, come il server che restituisce un errore 5xx, un timeout o un errore di connessione.

Cosa non viene riprovato: se il tuo endpoint rifiuta la richiesta stessa (qualsiasi 4xx), non riproviamo: inviare nuovamente la stessa richiesta produrrebbe solo lo stesso rifiuto.

Quali eventi vengono ritentati: webhook dei tag (contact_tags_updated), i tre eventi delle attività e il riepilogo giornaliero. Gli altri vengono inviati una sola volta, quindi per quelli l’interruttore non ha nulla su cui agire. Ogni evento contiene comunque X-Webhook-Delivery, quindi una regola di deduplicazione li copre tutti.

Attiva i tentativi solo se il tuo endpoint è idempotente. I tentativi significano che lo stesso evento può arrivare più di una volta. Usa l’intestazione X-Webhook-Delivery per riconoscere una ripetizione: rimane invariata in ogni tentativo per lo stesso evento, così puoi ignorare in sicurezza un ID che hai già gestito.

I tentativi interagiscono con lo spegnimento automatico dopo ripetuti fallimenti (vedere Affidabilità dei webhook) nel modo desiderato: il contatore dei fallimenti conta un’intera consegna, solo dopo che ogni tentativo è stato esaurito, non ogni singolo tentativo.

Affidabilità dei webhook #

• Your AI Connector invia webhook tramite una connessione sicura (HTTPS). Assicurati che l’indirizzo web fornito utilizzi HTTPS.
• Se il tuo sistema restituisce un errore, la consegna viene considerata non riuscita.
• Monitora l’uptime del tuo sistema ricevente per evitare di perdere eventi.
• Per flussi di lavoro critici, attiva Riprovare le consegne non riuscite e considera anche un meccanismo di fallback.

I webhook vengono disattivati automaticamente dopo ripetuti errori. Se l’URL del tuo webhook fallisce ripetutamente (circa 5 errori consecutivi, o 3 consecutivi per errori di configurazione), Your AI Connector smette automaticamente di inviare eventi a quell’URL. Per ripristinarlo una volta che l’endpoint è tornato operativo: modifica il webhook e salvalo con un URL diverso (qualsiasi modifica all’URL lo riabilita), oppure usa l’endpoint di riabilitazione tramite API; salvare nuovamente con lo stesso URL non è sufficiente. Anche il supporto può riabilitarlo per te.

Risoluzione dei problemi #

Prossimi passi #

• Integrazione GoHighLevel — usa i webhook per integrare Your AI Connector con GHL.
• Accesso API — combina i webhook con l’API per automazioni potenti.
• Utilizzo dei tag per etichettare i contatti — imposta tag che attivano i tuoi webhook.