Webhook
I webhook ti permettono di ricevere callback HTTP in tempo reale quando si verificano eventi sulle tue istanze WhatsApp. Invece di interrogare continuamente l’API, Wappfy invia gli eventi al tuo server nel momento in cui si verificano.Eventi supportati
Wappfy supporta 12 tipi di eventi webhook:Eventi dei messaggi
Eventi dei messaggi
Eventi delle istanze
Eventi delle istanze
Eventi di gruppi e contatti
Eventi di gruppi e contatti
Creare un webhook
Registra un endpoint webhook per iniziare a ricevere eventi.Opzioni di configurazione
Il campo
instance_id e opzionale. Se omesso, il webhook ricevera eventi da tutte le istanze del tuo account.Elencare i webhook
Aggiornare un webhook
Aggiorna l’URL, gli eventi o la configurazione di un webhook esistente.Eliminare un webhook
Formato del payload di consegna
Quando si verifica un evento, Wappfy invia una richiesta POST all’URL del tuo webhook con la seguente struttura:Campi del payload
Verifica della firma HMAC
Se fornisci unsecret durante la creazione del webhook, ogni consegna includera un header X-Wappfy-Signature contenente una firma HMAC-SHA256 del corpo della richiesta.
Verifica sempre questa firma per assicurarti che la richiesta provenga da Wappfy e non sia stata alterata.
Esempi di verifica
Comportamento dei tentativi
Se il tuo server non risponde con un codice di stato2xx entro il timeout_ms configurato, Wappfy ritentera la consegna.
I tentativi si fermano quando viene ricevuta una risposta
2xx o quando il retry_count e esaurito. Il numero predefinito di tentativi e 3.Visualizzare lo storico delle consegne
Controlla il log delle consegne di un webhook per vedere i tentativi passati e i relativi risultati.Esempi di payload degli eventi
message.received
message.received
message.delivered
message.delivered
message.read
message.read
message.reaction
message.reaction
instance.connected
instance.connected
instance.qr
instance.qr
group.joined
group.joined
Buone pratiche
Rispondi rapidamente
Restituisci uno stato
200 entro 5 secondi. Elabora l’evento in modo asincrono per evitare timeout.Deduplica
Usa l’
id della consegna per rilevare e saltare le consegne duplicate causate dai tentativi.Verifica le firme
Valida sempre l’header
X-Wappfy-Signature se hai configurato un segreto.Usa HTTPS
Gli URL dei webhook devono utilizzare HTTPS. Gli endpoint HTTP verranno rifiutati.