I webhook sono il modo piu semplice e immediato per far comunicare RecallAI con il tuo gestionale. Quando accade un evento in RecallAI (un recall viene completato, un appuntamento viene fissato, un contatto viene aggiornato), il sistema puo notificare automaticamente il tuo gestionale in tempo reale. Ecco come configurarli.
Cosa Sono i Webhook
Un webhook e una notifica HTTP automatica. Quando si verifica un evento, RecallAI invia una richiesta POST a un URL che tu specifichi, contenente i dati dell'evento in formato JSON. Il tuo gestionale riceve questi dati e li elabora come preferisce.
A differenza delle API tradizionali (dove il tuo sistema deve "chiedere" periodicamente se ci sono novita), i webhook funzionano in modalita push: e RecallAI a notificarti quando succede qualcosa. Questo significa dati sempre aggiornati, senza ritardi e senza polling continuo.
Eventi Disponibili
RecallAI puo inviare webhook per i seguenti eventi:
- recall.completed: un recall e stato completato (il cliente ha risposto)
- recall.no_response: un recall non ha ricevuto risposta entro il timeout
- appointment.created: un appuntamento e stato fissato tramite il recall
- appointment.cancelled: un appuntamento precedentemente fissato e stato cancellato
- contact.updated: i dati di un contatto sono stati modificati
- contact.opted_out: un contatto ha richiesto di non essere piu contattato
- campaign.completed: una campagna di recall ha raggiunto tutti i contatti target
Configurazione Passo-Passo
Passo 1: Ottieni l'URL di Destinazione
Il tuo gestionale deve avere un endpoint (URL) pronto a ricevere richieste POST. Se il tuo gestionale non ha questa funzionalita nativa, puoi usare servizi come Zapier, Make (ex Integromat) o n8n come intermediari. Consulta la pagina integrazioni per le opzioni disponibili.
Passo 2: Crea il Webhook in RecallAI
Vai in Impostazioni, poi Integrazioni, poi Webhook. Clicca su "Nuovo Webhook" e compila:
- Nome: un nome descrittivo (es. "Sync appuntamenti con gestionale")
- URL: l'endpoint del tuo gestionale
- Eventi: seleziona gli eventi che vuoi ricevere
- Segreto (opzionale): una stringa segreta per verificare l'autenticita delle notifiche
Passo 3: Testa il Webhook
Usa il pulsante "Invia Test" per inviare un evento di prova al tuo endpoint. Verifica che il tuo gestionale riceva e interpreti correttamente i dati.
Passo 4: Attiva e Monitora
Attiva il webhook e monitora le consegne dalla sezione Log. Puoi vedere ogni notifica inviata, la risposta del tuo sistema e eventuali errori.
Formato dei Dati
Ogni webhook invia un payload JSON con una struttura standard:
- event: il tipo di evento (es. "appointment.created")
- timestamp: quando e avvenuto l'evento
- data: i dati specifici dell'evento (contatto, appuntamento, campagna)
La documentazione completa con esempi per ogni tipo di evento e disponibile nella sezione Sviluppatori del pannello RecallAI.
Gestione degli Errori
Se il tuo endpoint non risponde o restituisce un errore, RecallAI ritenta automaticamente:
- Primo retry dopo 1 minuto
- Secondo retry dopo 5 minuti
- Terzo retry dopo 30 minuti
- Quarto retry dopo 2 ore
Se dopo 4 tentativi il webhook continua a fallire, viene disattivato automaticamente e ricevi una notifica. Questo protegge sia il tuo sistema sia il nostro da loop di errori.
Casi d'Uso Comuni
- Sincronizzare appuntamenti: quando un recall genera un appuntamento, il webhook lo crea automaticamente nell'agenda del gestionale
- Aggiornare lo stato del cliente: quando un recall viene completato, il gestionale aggiorna lo stato del paziente/cliente
- Notifiche interne: quando un cliente fa opt-out, il team riceve una notifica su Slack o Teams
- Alimentare un CRM: ogni interazione di recall aggiorna la timeline del contatto nel CRM
I webhook sono lo strumento piu potente per creare un ecosistema integrato dove RecallAI e il tuo gestionale lavorano insieme senza interruzioni. Scopri i piani che includono le integrazioni webhook.