
Nella Parte 1, abbiamo costruito uno script che legge da un database gli appuntamenti del giorno successivo, li carica in una campagna di SIP Caller tramite la REST API e la attiva, ogni giorno, con un cron job. Le chiamate partono da sole, ma i risultati restano in SIP Caller: il sistema della clinica non sa ancora quali pazienti hanno confermato, quali hanno chiesto di spostare l'appuntamento e quali non è stato possibile raggiungere.
In questa seconda parte, chiudiamo il cerchio. Un piccolo servizio web riceve da SIP Caller il risultato di ogni chiamata, nel momento in cui avviene, e lo registra nella stessa tabella appointments.
I webhook sono l'opposto di una chiamata API: invece di essere il tuo programma a chiedere i dati a SIP Caller, è SIP Caller a inviare i dati al tuo programma. Tu esponi un endpoint HTTPS, e SIP Caller gli invia una richiesta POST con un payload JSON ogni volta che si verifica un evento a cui è iscritto.
L'evento che ci serve è Chiamata Terminata. Viene inviato ogni volta che termina una chiamata effettuata da una campagna, qualunque sia il suo risultato, e include tutto ciò di cui abbiamo bisogno:
{
"id": "01a0f3d2-6c8e-7b15-a9d4-3e7f1b2c8a60",
"object": "event",
"apiVersion": 2,
"createdAt": "2026-11-03T10:02:41.512",
"type": "CallEnded",
"data": {
"campaign": {
"id": "01a0f2c7-3e1b-7a4d-9c58-2b6e8d1f0a93",
"name": "Appointment Reminders 2026-11-04",
"varNames": ["FirstName", "LastName", "AppointmentDate", "AppointmentTime", "AppointmentId"]
},
"callDetails": {
"callId": "01a0f3d1-f2a8-7c63-8e0b-5d9a4c1e7b32",
"number": "18005551234",
"varValues": ["John", "Carter", "Wednesday, November 4", "10:30 AM", "1"],
"attempt": 1,
"ringResult": "Answer",
"answerType": "Human",
"interactionResults": [
{ "id": "...", "type": "DtmfInput", "label": "Confirm appointment", "value": "1" }
],
"outcome": "Success",
"retryAt": null,
...
}
}
}Per brevità abbiamo omesso molti campi, come le durate, il sistema telefonico e i dettagli del trasferimento. Il riferimento di Chiamata Terminata li descrive tutti.
Ecco cosa conta per la nostra integrazione:
varValues contiene i valori delle variabili che abbiamo inviato nella Parte 1, nello stesso ordine di varNames. È qui che la variabile AppointmentId si rivela utile: ci indica esattamente a quale riga della tabella appointments appartiene questa chiamata, senza dover cercare il paziente in base al numero di telefono.interactionResults contiene le cifre premute dal paziente. Con il flusso di chiamata Promemoria appuntamento, 1 significa che l'appuntamento è confermato, e 2 che il paziente vuole fissare una nuova data.ringResult e answerType ci dicono se la chiamata ha ricevuto risposta, e da chi: una persona o una segreteria telefonica.outcome ci dice se il numero è concluso (Success o FailureWithNoRetryLeft), oppure se SIP Caller lo chiamerà di nuovo più tardi (FailureWithRetryPending), in base alle impostazioni dei tentativi della campagna. In quest'ultimo caso, dopo il tentativo successivo arriverà un altro evento Chiamata Terminata.Aggiungiamo tre colonne alla tabella appointments della Parte 1, per memorizzare il risultato del promemoria:
ALTER TABLE appointments
ADD COLUMN reminder_status VARCHAR(30),
ADD COLUMN reminder_attempts INTEGER,
ADD COLUMN reminder_call_id UUID;reminder_status contiene il risultato del promemoria, con uno di questi valori:| Stato | Significato |
|---|---|
Confirmed | Il paziente ha premuto 1 per confermare l'appuntamento. |
RescheduleRequested | Il paziente ha premuto 2, e la chiamata è stata trasferita al team. |
RetryPending | La chiamata non è andata a buon fine, ma SIP Caller riproverà. |
NotReached | Il numero era occupato, non ha risposto o la chiamata è fallita, senza tentativi rimasti. |
Voicemail | La chiamata ha raggiunto una segreteria telefonica, senza tentativi rimasti. |
NoResponse | Il paziente ha risposto, ma non ha premuto nessuna cifra valida. |
reminder_attempts contiene il numero di chiamate effettuate finora.reminder_call_id contiene l'ID dell'ultima chiamata, così puoi trovarla nei rapporti di SIP Caller se mai avessi bisogno di verificare cosa è successo.Il ricevitore è una piccola applicazione web costruita con Flask, il framework web leggero più diffuso per Python. Installalo nello stesso ambiente virtuale dello script della Parte 1, insieme a gunicorn, un server pronto per la produzione con cui eseguirlo:
cd /opt/appointment-reminders
.venv/bin/pip install flask gunicornPoi salva il seguente codice come webhook_receiver.py:
"""Receives Call Ended events from SIP Caller, and saves the result of each reminder call."""
import hashlib
import hmac
import json
import os
import psycopg
from flask import Flask, abort, request
SIGNING_SECRET = os.environ["SIPCALLER_WEBHOOK_SECRET"]
DATABASE_URL = os.environ["DATABASE_URL"]
# DTMF digits configured in the call flow to confirm and to reschedule the appointment
CONFIRM_DIGIT = "1"
RESCHEDULE_DIGIT = "2"
app = Flask(__name__)
def is_valid_signature(header, body):
try:
parts = dict(item.split("=", 1) for item in header.split(","))
message = parts["t"].encode() + b"." + body
except (KeyError, ValueError):
return False
expected = hmac.new(SIGNING_SECRET.encode(), message, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])
def get_reminder_status(call):
digits = [result["value"] for result in call.get("interactionResults") or [] if result["type"] == "DtmfInput"]
if CONFIRM_DIGIT in digits:
return "Confirmed"
if RESCHEDULE_DIGIT in digits:
return "RescheduleRequested"
if call["outcome"] == "FailureWithRetryPending":
return "RetryPending"
if call["ringResult"] != "Answer":
return "NotReached"
if call["answerType"] in ("Machine", "Voicemail"):
return "Voicemail"
return "NoResponse"
@app.post("/webhooks/sipcaller")
def receive_event():
body = request.get_data()
if not is_valid_signature(request.headers.get("Sip-Caller-Signature", ""), body):
abort(401)
event = json.loads(body)
if event["type"] != "CallEnded":
return "", 204
campaign = event["data"]["campaign"]
call = event["data"]["callDetails"]
if "AppointmentId" not in campaign["varNames"]:
return "", 204 # A call from a campaign that isn't an appointment reminder
appointment_id = int(call["varValues"][campaign["varNames"].index("AppointmentId")].strip())
with psycopg.connect(DATABASE_URL) as conn:
conn.execute(
"""
UPDATE appointments
SET reminder_status = %s, reminder_attempts = %s, reminder_call_id = %s
WHERE id = %s AND (reminder_attempts IS NULL OR reminder_attempts <= %s)
""",
(get_reminder_status(call), call["attempt"], call["callId"], appointment_id, call["attempt"]),
)
return "", 204Vediamolo nel dettaglio.
L'endpoint è pubblico, quindi chiunque ne scopra l'URL potrebbe inviargli risultati falsi. Per evitarlo, SIP Caller firma ogni richiesta con un segreto che conoscete solo tu e SIP Caller, e invia la firma nell'intestazione Sip-Caller-Signature. is_valid_signature calcola la firma del corpo grezzo con quel segreto e la confronta con quella ricevuta, esattamente come descritto in Verificare le firme. Le richieste con una firma mancante o errata vengono rifiutate con 401 Unauthorized.
Nota che la firma viene calcolata sul corpo esattamente come è stato ricevuto, ed è per questo che il codice lo legge con request.get_data() prima di analizzare il JSON.
Lo stesso webhook potrebbe essere assegnato ad altre campagne del tuo account, quindi il ricevitore ignora qualsiasi evento che non sia un evento Chiamata Terminata, o che provenga da una campagna senza la variabile AppointmentId. Per tutti gli altri, cerca la posizione di AppointmentId in varNames e prende il valore nella stessa posizione in varValues.
get_reminder_status trasforma i dettagli della chiamata in uno degli stati della nostra tabella. Le cifre premute dal paziente hanno la precedenza: se ha premuto 1 o 2, è tutto ciò che ci serve sapere. Altrimenti, lo stato dipende dal fatto che SIP Caller chiamerà di nuovo o meno, e da come è terminata la chiamata.
Se nel tuo flusso di chiamata hai configurato cifre diverse, ti basta modificare CONFIRM_DIGIT e RESCHEDULE_DIGIT.
Infine, un singolo UPDATE salva lo stato, il numero del tentativo e l'ID della chiamata. La condizione su reminder_attempts gestisce due aspetti della consegna dei webhook:
Il ricevitore risponde con 204 No Content non appena la riga è aggiornata. SIP Caller si aspetta una risposta rapida, come spiegato in Rispondere rapidamente. Un singolo UPDATE richiede pochi millisecondi, quindi puoi eseguirlo subito. Se la tua elaborazione richiede più tempo, ad esempio perché chiama un sistema esterno lento, rispondi prima ed esegui il lavoro in un processo in background.
A differenza dello script della Parte 1, il ricevitore deve essere sempre in esecuzione. Su Linux, il modo più semplice per farlo è un servizio systemd. Crea il file /etc/systemd/system/appointment-reminders-webhook.service:
[Unit]
Description=SIP Caller webhook receiver for appointment reminders
After=network.target
[Service]
WorkingDirectory=/opt/appointment-reminders
EnvironmentFile=/opt/appointment-reminders/.env
ExecStart=/opt/appointment-reminders/.venv/bin/gunicorn --bind 127.0.0.1:8000 webhook_receiver:app
Restart=always
[Install]
WantedBy=multi-user.targetLegge le sue impostazioni dallo stesso file .env dello script della Parte 1, quindi aggiungici il segreto di firma. Otterrai il segreto nel passo successivo:
SIPCALLER_WEBHOOK_SECRET=WEBHOOK_SIGNING_SECRETPoi abilita e avvia il servizio:
sudo systemctl enable --now appointment-reminders-webhookOra il servizio si avvia automaticamente all'accensione del server, e si riavvia se dovesse fermarsi.
Il ricevitore è in ascolto solo sul server stesso (127.0.0.1). Per renderlo raggiungibile da SIP Caller tramite HTTPS, metti davanti un server web. Caddy è un'opzione semplice, poiché ottiene e rinnova automaticamente il certificato TLS. Con un record DNS come reminders.example.com che punta al tuo server, questa è l'intera configurazione:
reminders.example.com {
reverse_proxy 127.0.0.1:8000
}Se usi già nginx o Apache, una regola di reverse proxy nella tua configurazione esistente svolge lo stesso compito.
Nella Console Web, vai su Impostazioni > Webhook e crea un nuovo webhook, come spiegato in Webhook:
https://reminders.example.com/webhooks/sipcaller.interactionResults, introdotto nella versione 2.Copia il segreto di firma del nuovo webhook nel file .env, e riavvia il servizio affinché lo legga:
sudo systemctl restart appointment-reminders-webhookPoi apri la campagna modello della Parte 1 e seleziona il nuovo webhook nella scheda Integrazione. Poiché lo script crea la campagna di ogni giorno duplicando il modello, ogni nuova campagna eredita automaticamente il webhook. Non c'è nulla da modificare nello script.
Alla successiva esecuzione della campagna, i risultati iniziano ad apparire nella tabella:
SELECT first_name, last_name, appointment_at, reminder_status, reminder_attempts
FROM appointments
WHERE appointment_at::date = '2026-11-04'; first_name | last_name | appointment_at | reminder_status | reminder_attempts
------------+-----------+---------------------+---------------------+-------------------
John | Carter | 2026-11-04 10:30:00 | Confirmed | 1
Jane | Miller | 2026-11-04 11:15:00 | RescheduleRequested | 1
Peter | Wilson | 2026-11-04 16:00:00 | RetryPending | 1Se non appare nulla, vai su Impostazioni > Webhook nella Console Web e fai clic sul webhook. Vedrai tutti gli eventi inviati e i dettagli di ogni tentativo di consegna, inclusi il codice di stato e la risposta del tuo ricevitore. Consulta Risoluzione dei problemi dei webhook per maggiori dettagli.
Con i risultati nel database, il sistema della clinica può agire di conseguenza. Alcune idee:
GROUP BY reminder_status mostra quanti pazienti confermano ogni giorno, e come questo dato cambia nel tempo.Ad esempio, questa query elenca i prossimi appuntamenti i cui pazienti hanno chiesto di fissare una nuova data:
SELECT first_name, last_name, phone_number, appointment_at
FROM appointments
WHERE reminder_status = 'RescheduleRequested'
AND appointment_at >= now();Se non puoi esporre un endpoint HTTPS, ad esempio perché il tuo database si trova in una rete che non accetta connessioni in entrata, puoi comunque ottenere i risultati interrogando periodicamente la REST API. Il rapporto Dettagli dei numeri restituisce lo stato di ogni numero di una campagna, e lo script della Parte 1 potrebbe leggerlo a fine giornata.
Quando puoi usarli, i webhook restano comunque l'opzione migliore: i risultati arrivano in pochi secondi, non invii richieste che non restituiscono nulla di nuovo, e non vengono conteggiati nei limiti di frequenza dell'API.
In questi due articoli, abbiamo costruito un'integrazione completa tra SIP Caller e un database esterno:
Nessuno deve esportare un file, caricare un elenco o copiare a mano un risultato. E anche se il nostro esempio riguarda gli appuntamenti, lo stesso schema funziona per il recupero crediti, i rinnovi, i sondaggi o qualsiasi altra campagna i cui dati risiedono nei tuoi sistemi.
Il codice completo di entrambi i programmi si trova in questi due articoli. Usalo come punto di partenza e adattalo alle tue tabelle e ai tuoi flussi di chiamata.
👉 Hai bisogno di aiuto per costruire la tua integrazione? Contatta il nostro team e saremo lieti di aiutarti.

Un esempio passo dopo passo per collegare SIP Caller a un database esterno. Un breve script Python legge da una tabella PostgreSQL gli appuntamenti del giorno successivo, crea una campagna a partire da un modello, carica i numeri con valori delle variabili personalizzati e la attiva tramite la REST API. Un cron job lo esegue poi ogni giorno, così le tue campagne vengono alimentate senza alcun intervento manuale.

La composizione manuale ha un costo reale, anche se non appare mai come una singola voce nel budget: tempo di composizione sprecato, numeri sbagliati, follow-up mancati e opportunità perse lungo il percorso. Analizziamo ciascuno di questi fattori di costo e presentiamo esempi di calcolo del ROI per mostrare quanto la composizione automatizzata può effettivamente far risparmiare al tuo team.

Le agenzie governative sono sotto costante pressione per comunicare in modo rapido, chiaro ed efficiente con ampie popolazioni. Che si tratti di notificare ai cittadini la chiusura di strade, coordinare la risposta alle emergenze, ricordare appuntamenti ai residenti o migliorare la riscossione delle tasse, una comunicazione tempestiva è fondamentale. I metodi di comunicazione tradizionali, come le chiamate telefoniche manuali o gli avvisi stampati, sono spesso troppo lenti e dispendiosi in termini di risorse. Per questo motivo, molte organizzazioni pubbliche stanno adottando soluzioni di chiamata automatizzata in uscita come SIP Caller per semplificare la comunicazione con i cittadini e migliorare i tempi di risposta. In questo articolo esploriamo come le agenzie governative possono utilizzare i dialer predittivi e di potenza per migliorare la comunicazione pubblica e il coinvolgimento dei cittadini.