Ricevere i codici SMS e delle chiamate vocali con un webhook: guida all'API

Un webhook invia al tuo server ogni SMS e ogni chiamata sul tuo numero. Una chiamata breve arriva con il suo testo e il codice letto ad alta voce.

Un webhook invia al tuo server ogni SMS e ogni chiamata sul tuo numero nel momento in cui arriva. Da novembre 2026 una chiamata breve arriva insieme al suo testo e al codice letto ad alta voce, quindi un codice vocale raggiunge il tuo codice sotto forma di testo.

Questa guida configura il ricevitore, verifica che ogni richiesta provenga davvero da noi e gestisce entrambi i tipi di codice. Presuppone che tu abbia già una chiave API e un numero; se non è così, parti da automatizzare la verifica via SMS con l'API.

Perché alcuni codici arrivano come chiamata

Molti servizi offrono l'opzione «chiamami» quando l'SMS non arriva, e alcuni inviano solo codici vocali. Un robot legge le cifre ad alta voce. Con un numero privato di SMS Activate App, quella chiamata raggiunge il tuo numero proprio come un SMS.

Ogni chiamata registrata che dura fino a un minuto viene trasformata in testo quando arriva. Ricevi:

  • transcript: ciò che è stato detto nella chiamata, oppure null.
  • code: il codice di verifica letto nella chiamata (da 4 a 8 cifre), oppure null.
  • transcriptStatus: done, empty (nessun parlato), failed, toolong (oltre un minuto), overbudget oppure off.

Il link alla registrazione resta valido per 24 ore. Il testo invece resta salvato.

Passo 1: collega il numero al tuo server

Imposta il webhook per un numero:

L'indirizzo deve essere HTTPS e rispondere alla nostra verifica con uno stato 2xx prima di essere salvato. Per ricevere gli eventi di tutti i tuoi numeri insieme, imposta invece webhookUrl sull'account con PATCH /v1/me.

Passo 2: ottieni il segreto di firma

La risposta è {"secret": "whsec_..."} e viene mostrata una sola volta. Conserva il segreto insieme alla tua chiave API. Ogni chiamata emette un nuovo segreto e quello vecchio smette di valere alla consegna successiva, quindi ruotalo solo quando puoi aggiornare il server nello stesso momento.

Passo 3: verifica ogni richiesta

Ogni richiesta contiene tre header:

  • x-vpn-event: sms.received, call.received, recording.ready e altri.
  • x-vpn-timestamp: il momento della firma, come timestamp Unix (secondi).
  • x-vpn-signature: v1= seguito da un HMAC-SHA256 in esadecimale.

La firma è un HMAC-SHA256 calcolato con il tuo segreto su v1.<timestamp>.<raw body>. Calcolala sui byte grezzi, prima di qualsiasi parsing JSON, e rifiuta un timestamp che si discosta di più di cinque minuti dall'orologio del tuo server.

In Node.js con Express:

Rispondi subito con uno stato 2xx e svolgi il lavoro lento in un secondo momento.

Passo 4: prendi il codice da entrambi i tipi di evento

Un SMS (sms.received):

La registrazione di una chiamata (recording.ready, qualche secondo dopo la fine della chiamata):

Un solo handler copre entrambi i casi:

Usa il campo code invece di analizzare tu stesso la trascrizione: il robot spesso ripete le cifre o le legge una per una, e code le contiene già come un'unica stringa.

Passo 5: prova tutto prima del traffico reale

  • POST /v1/me/webhook-test invia un evento webhook.test al tuo ricevitore.
  • GET /v1/me/webhook-deliveries elenca le ultime consegne: l'evento, se è stato consegnato, il codice di stato del tuo server e il numero di tentativi.

Se una consegna fallisce, guarda prima qui: un segreto sbagliato, un body analizzato prima della verifica o una risposta lenta sono le cause più comuni.

Senza webhook? Leggi le chiamate con l'API

Se non hai un server, leggi le chiamate di un numero quando ti servono:

Ogni chiamata contiene gli stessi campi transcript, code e transcriptStatus. Nel tuo account sul sito, il codice compare sotto la chiamata e si copia con un tocco.

Quanto costano chiamate e SMS

Le chiamate in entrata (al minuto) e gli SMS su un numero vengono addebitati sul tuo saldo a un prezzo per paese, restituito come usagePricing (callCents, smsCents, advanceUsd) nei paesi, nei risultati di ricerca e nei tuoi numeri. Con il saldo a zero un numero continua a funzionare fino a un piccolo anticipo; oltre quel limite le chiamate in entrata vengono rifiutate finché non ricarichi, mentre gli SMS continuano ad arrivare. Vedi i prezzi.

Prossimi passi