Skip to main content

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:

Creare un webhook

Registra un endpoint webhook per iniziare a ricevere eventi.
Risposta:

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

Risposta:

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 un secret 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

Usa sempre un confronto a tempo costante (come timingSafeEqual o hmac.compare_digest) durante la verifica delle firme per prevenire attacchi di timing.

Comportamento dei tentativi

Se il tuo server non risponde con un codice di stato 2xx 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.
Risposta:

Esempi di payload degli eventi


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.