Documentazione/Integrazioni/Configurare webhook
Integrazioni

Configurare webhook per le notifiche

Ricevi notifiche in tempo reale sulle chiamate del tuo assistente e integra fono24 con i tuoi sistemi.

Cosa sono i webhook?

I webhook sono chiamate HTTP che fono24 invia al tuo server quando si verificano determinati eventi, come l'inizio o la fine di una chiamata. Ti permettono di:

  • Ricevere notifiche in tempo reale
  • Salvare i dati delle chiamate nel tuo CRM
  • Inviare email o SMS di follow-up
  • Aggiornare dashboard e statistiche
  • Attivare automazioni personalizzate

Eventi disponibili

call.started

Una nuova chiamata è iniziata

call.completed

La chiamata è terminata con successo

call.failed

La chiamata è fallita o è stata interrotta

transcript.ready

La trascrizione della chiamata è disponibile

Configurazione

Per configurare un webhook:

  1. Vai su Impostazioni → Integrazioni → Webhook
  2. Inserisci l'URL del tuo endpoint (deve essere HTTPS)
  3. Seleziona gli eventi che vuoi ricevere
  4. Salva la configurazione

Requisiti endpoint

  • • L'URL deve usare HTTPS (non HTTP)
  • • Deve rispondere con status 200 entro 30 secondi
  • • Deve accettare richieste POST con JSON

Formato del payload

Ogni webhook invia un payload JSON con questa struttura:

{
  "event": "call.completed",
  "timestamp": "2024-01-15T14:30:00Z",
  "data": {
    "call_id": "call_abc123",
    "assistant_id": "asst_xyz789",
    "phone_number": "+39021234567",
    "caller_number": "+393331234567",
    "duration_seconds": 145,
    "status": "completed",
    "direction": "inbound",
    "transcript": "...",
    "summary": "Il cliente ha richiesto informazioni sui servizi...",
    "sentiment": "positive",
    "cost_credits": 2.18
  }
}

Esempi di implementazione

Node.js (Express)

server.js
const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook/fono24', (req, res) => {
  const { event, data } = req.body;

  switch (event) {
    case 'call.started':
      console.log('Nuova chiamata:', data.caller_number);
      break;
    case 'call.completed':
      console.log('Chiamata completata:', data.call_id);
      // Salva nel database, invia email, etc.
      break;
    case 'call.failed':
      console.error('Chiamata fallita:', data.error);
      break;
  }

  res.status(200).json({ received: true });
});

app.listen(3000);

Python (Flask)

app.py
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook/fono24', methods=['POST'])
def handle_webhook():
    data = request.json
    event = data.get('event')

    if event == 'call.completed':
        call_data = data.get('data', {})
        # Processa la chiamata completata
        save_to_database(call_data)
        send_notification(call_data)

    return jsonify({'received': True}), 200

if __name__ == '__main__':
    app.run(port=3000)

Sicurezza

Per verificare che le richieste provengano da fono24:

Verifica l'header X-Fono24-Signature con il tuo secret
Accetta solo richieste da IP autorizzati
Implementa rate limiting sul tuo endpoint
Logga tutte le richieste per debugging

Retry e gestione errori

Se il tuo endpoint non risponde o restituisce un errore, fono24 riproverà automaticamente:

  • 1° retry: dopo 1 minuto
  • 2° retry: dopo 5 minuti
  • 3° retry: dopo 30 minuti

Dopo 3 tentativi falliti, il webhook viene segnato come fallito e puoi vederlo nella dashboard.

Testing

Puoi testare i webhook dalla dashboard usando il pulsante "Invia Test". Per sviluppo locale, puoi usare strumenti come:

Prompt EfficaciKnowledge Base