Webhook Chat GTG: integrazione esterna

Introduzione

I webhook permettono a Chat G Tech Group di notificare in tempo reale sistemi esterni quando avvengono eventi specifici (nuova conversazione, messaggio ricevuto, chiusura, valutazione CSAT). Sono lo strumento fondamentale per integrazioni custom con CRM, ERP, marketing automation.

Cosa è un webhook

Un webhook è una chiamata HTTP POST che Chat GTG invia automaticamente al tuo endpoint quando si verifica un'evento configurato. Il body della richiesta contiene un JSON con i dettagli dell'evento. Il tuo server può quindi reagire (creare ticket, inviare email, aggiornare CRM, ecc.).

Eventi disponibili

I principali eventi:

• conversation.created: nuova chat aperta
• conversation.assigned: chat assegnata a operatore
• conversation.closed: chat chiusa
• message.created: nuovo messaggio (cliente o operatore)
• csat.received: ricevuta valutazione
• tag.added: tag applicato
• contact.created: nuovo contatto registrato

Configurazione

Vai in Impostazioni > Webhook > Nuovo. Inserisci:

• URL endpoint (es. https://miosito.it/api/chat-webhook)
• Eventi da sottoscrivere (uno o più)
• Secret per firma HMAC (consigliato)
• Stato (attivo/disattivo)

Struttura payload

Esempio payload conversation.created:

{
  "event": "conversation.created",
  "timestamp": "2026-06-29T14:30:00Z",
  "data": {
    "conversation_id": "conv_abc123",
    "channel": "widget",
    "customer": {"email": "mario@example.com"},
    "team_id": 5
  }
}

Firma HMAC

Per verificare l'autenticità del webhook (evitare attacchi spoofing), Chat GTG aggiunge un'header X-GTG-Signature con firma HMAC-SHA256 del body usando il secret configurato. Il tuo server deve ricalcolare la firma e confrontarla.

Risposta attesa

Il tuo endpoint deve rispondere con HTTP 200 entro 5 secondi. Risposte 4xx/5xx vengono considerate fallimento. Chat GTG riprova con backoff esponenziale: 1 min, 5 min, 30 min, 2h, 12h. Dopo 5 tentativi falliti l'evento viene segnato come definitivamente fallito.

Idempotenza

Ogni evento ha un event_id univoco. Il tuo endpoint deve gestire la deduplicazione (es. ignorare event_id già processati). Importante perché in caso di retry lo stesso evento può essere inviato più volte.

Log e debug

In Webhook > Log vedi tutti gli eventi inviati negli ultimi 30 giorni con: timestamp, evento, status HTTP risposta, tempo di risposta, payload completo. Filtra per webhook o tipo evento.

Test webhook

Usa la funzione Test nel pannello: invia un payload di esempio al tuo endpoint per verificare configurazione e gestione. Strumenti utili per debug: webhook.site, ngrok per esporre localhost.

Best practice

• Endpoint deve essere veloce (< 1 secondo): processa asincrono
• Verifica sempre la firma HMAC
• Gestisci idempotenza
• Monitora i fallimenti webhook nel tuo sistema
• Ruota periodicamente il secret HMAC

Hai bisogno di aiuto?

Se vuoi attivare Chat G Tech Group sul tuo sito, scrivici tramite il modulo di contatto.