Vai al contenuto
Wbiztool

Guide del prodotto

Webhook dei messaggi in arrivo (listener)

Un listener collega uno dei tuoi numeri WhatsApp a Unibox e può inviare un webhook per i messaggi in entrata al tuo server. Nella dashboard, i listener si gestiscono nella pagina Trigger in Ingresso. Quando un numero diventa listener, le sue chat vengono sincronizzate nella posta in arrivo Unibox e, se aggiungi un URL webhook, Wbiztool invia ogni nuovo messaggio al tuo server. Usa i webhook per registrare le conversazioni in un CRM, avvisare il tuo team o creare una risposta automatica.

Prima di iniziare#

  • Il componente aggiuntivo Unibox. Costa $20/mese o $200/anno per numero WhatsApp, e il numero di listener che puoi avere è pari alla quantità del componente aggiuntivo. Acquistalo in Componenti Aggiuntivi Disponibili su Fatturazione e Piani all'interno della dashboard. Senza di esso, la pagina Trigger in Ingresso si apre comunque, ma facendo clic su Aggiungi Nuovo Listener compare Unibox Add-on Required (componente aggiuntivo Unibox richiesto) con un pulsante Subscribe to Unibox Add-on (abbonati al componente aggiuntivo Unibox).
  • Un numero WhatsApp collegato in Impostazioni WhatsApp. Si possono aggiungere solo numeri collegati che non sono ancora listener.
  • Devi essere proprietario o editor dello spazio di lavoro.
  • Per i webhook: un URL pubblico (usa https) di al massimo 100 caratteri che accetti richieste POST con un corpo JSON.

Aggiungere un listener#

  1. Apri Trigger in Ingresso

    Nella barra laterale, apri UniBox e fai clic su Trigger in Ingresso, oppure vai a Trigger in Ingresso.

  2. Crea un nuovo listener

    Fai clic sulla scheda Aggiungi Nuovo Listener.

  3. Scegli il numero

    Selezionalo in Seleziona Numero WhatsApp. Se l'elenco mostra No available WhatsApp numbers (nessun numero WhatsApp disponibile), tutti i numeri collegati sono già listener oppure nessun numero è collegato.

  4. Aggiungi un webhook (facoltativo)

    Inserisci il tuo URL Webhook (Opzionale). Quando scrivi un URL, compare Webhook Events (eventi webhook): lascia selezionati Incoming Messages (messaggi in entrata), Outgoing Messages (messaggi in uscita) o entrambi. Puoi aggiungere o modificare l'URL in seguito.

  5. Salva

    Fai clic su Aggiungi Listener. Il listener compare come scheda con lo stato Active (attivo). Se hai inserito un URL, viene creato un secret webhook per quell'URL.

Gestire i listener#

Ogni scheda mostra il numero, il suo stato, l'URL Webhook: (oppure Non configurato), Ultima Attività: (quando è stata eseguita l'ultima verifica dei messaggi del numero, oppure Mai) e il Segreto Webhook:, nascosto finché non fai clic sul pulsante a forma di occhio.

Apri il menu di una scheda per:

AzioneCosa succede
ModificaCambia l'URL webhook, gli eventi webhook o il secret. Il numero non si può cambiare.
Disabilita / AbilitaDisabilitando, il listener passa a Inactive (inattivo): il numero smette di sincronizzarsi con la posta in arrivo e non vengono inviati webhook. Abilitandolo torna Active.
EliminaRimuove il listener dopo la tua conferma. Le conversazioni già presenti nella posta in arrivo restano. Se in seguito aggiungi di nuovo lo stesso numero, il listener viene ripristinato. Se inserisci un URL webhook quando lo aggiungi di nuovo, il listener mantiene il suo secret webhook precedente, se ne aveva uno, invece di riceverne uno nuovo.

Stati del listener#

StatoSignificato
ActiveI messaggi si sincronizzano e i webhook vengono inviati finché il numero è collegato.
Pending (in attesa)Il numero non era collegato quando il listener è stato creato, ad esempio da Zapier. Fai clic su Abilita quando il numero è collegato.
InactiveDisabilitato. Non si sincronizza nulla e non vengono inviati webhook.

Statistiche#

RiquadroCosa mostra
Listener AttiviTutti i listener della pagina, compresi quelli disabilitati.
Numeri DisponibiliNumeri collegati che non sono ancora listener. I numeri di cui hai eliminato il listener contano ancora come usati, quindi qui può comparire un valore inferiore a quanti puoi effettivamente aggiungerne.
Limite TotaleQuanti listener consente il tuo componente aggiuntivo Unibox.
Messaggi OggiNon ancora conteggiato; mostra sempre 0.

Modificare l'URL o gli eventi del webhook#

  1. Apri il listener

    Fai clic su nella scheda, poi su Modifica.

  2. Aggiorna le impostazioni

    Modifica Webhook URL (Optional) (URL webhook, facoltativo) e Webhook Events. Svuota l'URL per interrompere i webhook per questo numero: viene rimosso anche il suo secret, e se aggiungi di nuovo un URL ne viene creato uno nuovo.

  3. Salva

    Fai clic su Update Listener (aggiorna listener).

Rigenerare il secret#

In Edit Listener (modifica listener), fai clic sul pulsante di aggiornamento accanto a Webhook Secret e conferma. Il nuovo secret viene salvato subito, anche se poi chiudi la finestra senza fare clic su Update Listener, e da quel momento le richieste vengono firmate con il nuovo secret. Aggiorna immediatamente il tuo server con il nuovo secret.

Come vengono consegnati i webhook#

Wbiztool invia una richiesta POST al tuo URL per ogni nuovo messaggio trovato durante la sincronizzazione del numero, che avviene a intervalli di pochi minuti finché il numero è collegato e non è occupato a inviare messaggi.

  • Eventi: message_received per i messaggi che le persone inviano al tuo numero e message_sent per i messaggi inviati dal tuo numero (dal telefono, dalle campagne o dall'API). Vengono inviati solo gli eventi selezionati in Webhook Events.
  • Le risposte inviate dalla posta in arrivo Unibox di solito non attivano message_sent, perché la posta in arrivo le contiene già quando viene eseguita la sincronizzazione.
  • Risposta: rispondi con HTTP 200 entro 8 secondi. Qualsiasi altra risposta o un timeout conta come consegna non riuscita.
  • Nessun nuovo tentativo: ogni messaggio viene inviato una sola volta. Se il tuo server non è raggiungibile, quel webhook va perso.
  • Ordine: le richieste vengono inviate in modo indipendente e possono arrivare in ordine diverso. Ordina per message.timestamp se l'ordine è importante.
HeaderValore
Content-Typeapplication/json
X-Wbiztool-Eventmessage_received o message_sent
X-Wbiztool-TimestampQuando è stato inviato il webhook, in ISO 8601 UTC. Uguale a timestamp nel corpo.
X-Wbiztool-Webhook-IdL'ID del listener. Uguale a webhook_id nel corpo.
X-Wbiztool-Signaturesha256= seguito dalla firma. Viene inviato ogni volta che il listener ha un secret, cosa che avviene sempre quando è impostato un URL.

Payload#

Esempi di corpo del webhook
{
  "event": "message_received",
  "timestamp": "2026-09-16T10:31:12.482913+00:00",
  "webhook_id": 42,
  "whatsapp_client_id": "678",
  "whatsapp_phone": "919812345678",
  "message": {
    "id": "[email protected]_3EB0C1A2B3D4E5F60718",
    "type": "chat",
    "content": "Hi, is my order #4821 out for delivery?",
    "from": "919876543210",
    "from_name": "Aman",
    "to": "919812345678",
    "timestamp": "2026-09-16T10:29:58+00:00",
    "whatsapp_timestamp": 1789554598,
    "direction": "incoming",
    "status": "pending",
    "is_forwarded": false,
    "forwarding_score": 0
  },
  "contact": {
    "whatsapp_id": "[email protected]",
    "phone": "919876543210",
    "name": "Aman",
    "is_group": false,
    "is_business": false
  },
  "organisation": {
    "id": "10314",
    "name": "Acme Stores"
  }
}

Numeri, ID e nomi qui sopra sono esempi.

Campi di primo livello#

CampoTipoDescrizione
eventstringmessage_received o message_sent.
timestampstringQuando è stato inviato il webhook (ISO 8601, UTC).
webhook_idintegerL'ID del listener.
whatsapp_client_idstringID del tuo numero WhatsApp, come mostrato in Impostazioni WhatsApp.
whatsapp_phonestringIl tuo numero WhatsApp.
messageobjectIl messaggio. Vedi sotto.
contactobjectLa persona o il gruppo con cui si svolge la conversazione. Vedi sotto.
organisationobjectid (string) e name del tuo spazio di lavoro.
groupobjectSolo per le chat di gruppo: name, il nome del gruppo.

Campi di message#

CampoTipoDescrizione
idstringL'ID assegnato da WhatsApp al messaggio. Usalo per ignorare i duplicati.
typestringchat per il testo. Altrimenti il tipo di WhatsApp, ad esempio image, video, audio, ptt (nota vocale), document, sticker o location.
contentstringIl testo per i messaggi chat. Per i contenuti multimediali, invece, un'etichetta: 📸 Image, 🎥 Video, 🎵 Audio, 🎤 Voice Message, 😊 Sticker, Document: seguito dal testo del documento (Document quando non c'è testo), oppure il nome del tipo con l'iniziale maiuscola per tutto il resto, come Location. Le didascalie non sono incluse.
fromstringSempre il numero del contatto (o l'ID del gruppo), in entrambe le direzioni.
from_namestringIl nome del contatto o del gruppo. Può essere vuoto.
tostringSempre il tuo numero WhatsApp, in entrambe le direzioni.
timestampstringQuando il messaggio è stato inviato su WhatsApp (ISO 8601, UTC).
whatsapp_timestampintegerLo stesso orario come timestamp Unix in secondi.
directionstringincoming o outgoing. Usa questo campo, non from e to, per capire la direzione.
statusstringAttualmente sempre pending. Non farci affidamento per lo stato di consegna o di lettura.
is_forwardedbooleanSe il messaggio è stato inoltrato.
forwarding_scoreintegerQuante volte è stato inoltrato.
mediaobjectPer i messaggi multimediali, quando i dettagli sono disponibili: filename, mimetype e size in byte. Il file stesso non è incluso.
quoted_message_idstringSolo quando il messaggio risponde a un altro messaggio.

Campi di contact#

CampoTipoDescrizione
whatsapp_idstringL'ID WhatsApp, ad esempio [email protected] per una persona o …@g.us per un gruppo.
phonestringIl numero senza +, oppure l'ID del gruppo per i gruppi.
namestringIl nome che Wbiztool ha per il contatto, oppure il nome del gruppo. Può essere vuoto.
is_groupbooleantrue per le chat di gruppo.
is_businessbooleantrue per gli account WhatsApp Business, quando noto.

Verificare la firma#

Ogni richiesta è firmata con il secret del tuo listener tramite HMAC-SHA256. La firma è calcolata sul corpo grezzo della richiesta esattamente come ricevuto e inviata in X-Wbiztool-Signature come sha256= seguito dal digest esadecimale in minuscolo.

Calcola sempre la firma dai byte grezzi prima di analizzare il JSON. Analizzare e ricodificare il corpo lo modifica (ad esempio, i caratteri non inglesi e le emoji arrivano con escape come \uXXXX) e la firma non corrisponderà.

// Express: keep the raw body for this route
import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.WBIZTOOL_WEBHOOK_SECRET;

app.post("/wbiztool/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const expected = "sha256=" + crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const received = req.get("X-Wbiztool-Signature") || "";

  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.status(401).send("Invalid signature");

  const data = JSON.parse(req.body.toString("utf8"));
  if (data.event === "message_received") {
    console.log(`New message from ${data.contact.phone}: ${data.message.content}`);
  }
  res.sendStatus(200); // reply quickly; do slow work in the background
});

app.listen(3000);

La firma non copre l'header del timestamp, quindi non protegge dal replay di una richiesta. Se per te è importante, memorizza ogni message.id che hai elaborato e ignora le ripetizioni.

Risoluzione dei problemi#

Messaggio o problemaCosa fare
Unibox Add-on Required quando fai clic su Aggiungi Nuovo ListenerIl tuo spazio di lavoro non ha il componente aggiuntivo Unibox. Acquistalo in Componenti Aggiuntivi Disponibili su Fatturazione e Piani all'interno della dashboard.
You have reached your unibox numbers limitHai raggiunto il limite di numeri Unibox. Elimina un listener che non ti serve più oppure aumenta la quantità del componente aggiuntivo.
No available WhatsApp numbersCollega un altro numero, oppure il numero è già un listener.
This WhatsApp number is already a listenerIl numero è già un listener. Modifica la scheda esistente.
Invalid WhatsApp clientIl numero si è scollegato. Ricollegalo in Impostazioni WhatsApp e ricarica la pagina.
Errore che menziona value too long durante il salvataggioL'URL webhook supera i 100 caratteri. Usa un URL più breve.
Non arriva nessun webhookVerifica che il listener sia Active, che il numero sia collegato, che il tipo di evento sia selezionato e che il tuo URL sia pubblico, in https e con un certificato valido. I messaggi vengono inviati solo dopo la sincronizzazione successiva, qualche minuto più tardi.
Mancano alcuni webhookIl tuo server ha restituito una risposta diversa da 200, ha impiegato più di 8 secondi o non era raggiungibile. Le consegne non riuscite non vengono ritentate.
La firma non corrispondeUsa il corpo grezzo, non il JSON ricodificato, e il secret attuale. Rigenerare il secret, o collegare Zapier, lo sostituisce.
Ultima Attività: mostra MaiIl numero non è ancora stato verificato. Deve essere collegato e non occupato a inviare messaggi.

Pagine correlate#