Webhook
Ricevi messaggi in arrivo, conferme di consegna e cambi di stato.
Registri un URL e Genuka WA ti consegna lì ogni evento come POST firmato.
Registrare un endpoint
Nel portale, in Webhook: inserisci l'URL (HTTPS obbligatorio) e spunta gli eventi che vuoi
ricevere. Il segreto di firma (whsec_…) viene mostrato una sola volta, alla creazione.
Un endpoint può coprire tutti i numeri del tuo account (generale), un'azienda collegata o un solo numero di telefono; e un'azienda può essere esclusa da un endpoint generale.
Eventi disponibili
| Evento | Contenuto |
|---|---|
messages | Messaggi in arrivo e stati dei messaggi che hai inviato |
message_template_status_update | Un modello è stato approvato, rifiutato o messo in pausa |
account_update | Modifica dell'account: verifica, restrizione, sospensione |
phone_number_quality_update | È cambiata la qualità o il livello di invio di un numero |
connection.connected | Un numero è appena stato collegato tramite il tuo link, con il tuo ref (vedi Collegare un numero) |
call.connect · call.status_changed · call.terminated | Chiamate WhatsApp (piano Growth o superiore): una chiamata arriva o inizia (con l'SDP in data.session), cambia stato, termina (vedi Collegare un agente vocale) |
call.permission_replied | Un cliente ha risposto a una richiesta di permesso di chiamata. Arriva anche in messages, dato che è un messaggio. |
La piattaforma non ha una posta in arrivo: i webhook sono il modo per leggere le risposte.
Il payload
Ogni consegna è un POST che contiene un solo evento. data è il valore grezzo di Meta, non
modificato, tranne per gli eventi emessi dalla piattaforma stessa (connection.connected); i campi intorno ti dicono a quale azienda e a quale numero appartiene.
{
"id": "dlv_2f8c1a...",
"type": "message_status",
"field": "messages",
"created_at": "2026-08-04T09:31:07.412Z",
"partner_id": "cl9x...",
"company_id": "cm31...",
"connection_id": "cn77...",
"waba_id": "102290129340398",
"phone_number_id": "106540352242922",
"data": {
"id": "wamid.HBgLMjM3...",
"status": "delivered",
"timestamp": "1785836801",
"recipient_id": "237699000000"
}
}Header
| Header | Contenuto |
|---|---|
X-Genuka-Signature | La firma (vedi sotto) |
X-Genuka-Event | Tipo di evento, per esempio message_status |
X-Genuka-Event-Field | Il campo webhook di Meta sottostante, oppure il nome dell'evento quando non proviene da Meta |
X-Genuka-Delivery | Id della consegna, identico tra i tentativi: usalo per eliminare i duplicati |
X-Genuka-Webhook-Id | L'endpoint destinatario |
X-Genuka-Attempt | Numero del tentativo, a partire da 1 |
Verificare la firma
L'header è X-Genuka-Signature, nella forma t=1785836801,v1=5f3c…, dove v1 è l'HMAC-SHA256
esadecimale di `${t}.${rawBody}` con il tuo segreto come chiave.
Il timestamp è incluso nel MAC: è ciò che impedisce di reinviare una richiesta intercettata. Un
ricevitore rifiuta qualsiasi t fuori dalla sua finestra di tolleranza (300 secondi di default), e
t non può essere modificato senza invalidare v1.
Firma il corpo grezzo, esattamente come ricevuto. Un JSON.parse seguito da un
JSON.stringify cambia l'ordine delle chiavi e gli spazi: la firma non corrisponderà mai.
import { verifySignature } from "@genuka/whatsapp/webhooks";
export async function POST(request: Request) {
const raw = await request.text();
const signature = request.headers.get("x-genuka-signature");
if (!(await verifySignature(process.env.WEBHOOK_SECRET!, raw, signature))) {
return new Response("invalid signature", { status: 401 });
}
// Elabora in modo asincrono e rispondi subito.
void handle(JSON.parse(raw));
return new Response("ok");
}Versione minima: @genuka/whatsapp 0.1.1
verifySignature riconosce entrambi gli schemi e applica l'algoritmo corrispondente: il formato
con timestamp di Genuka WA (t=…,v1=…) e quello di Meta (X-Hub-Signature-256), quest'ultimo
utile solo se ricevi anche webhook di Meta direttamente. Nella 0.1.0 era gestito solo il formato
di Meta: la verifica di un webhook Genuka WA falliva sempre.
Se non usi la libreria, l'algoritmo sta in poche righe:
import crypto from "node:crypto";
const TOLERANCE_SECONDS = 300;
export function verify(rawBody: string, header: string, secret: string): boolean {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const timestamp = Number(parts.t);
// Rifiuta tutto ciò che è fuori dalla finestra: è questo che rende inutile
// reinviare più tardi una richiesta intercettata.
if (Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${timestamp}.${rawBody}`)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(parts.v1, "utf8"),
Buffer.from(expected, "utf8"),
);
}Ruota il segreto se sospetti che sia stato esposto
La rotazione ha effetto immediato: il segreto precedente smette di verificare appena lo ruoti, quindi aggiorna il tuo ricevitore nello stesso momento.
Tre regole di elaborazione
Rispondi 200 subito
Esegui l'elaborazione in background. Un endpoint lento provoca nuove consegne, che amplificano il carico proprio nel momento peggiore.
Gli eventi possono essere duplicati. Lo stesso messaggio può esserti consegnato due volte. Rendi
la tua elaborazione idempotente usando l'id del messaggio (wamid) o X-Genuka-Delivery.
L'ordine non è garantito. Una conferma di lettura può arrivare prima della conferma di consegna
dello stesso messaggio. Non far mai regredire uno stato: l'ordine logico è sent → delivered →
read, e failed è terminale.
Stati di un messaggio inviato
| Stato | Significato |
|---|---|
sent | Accettato dai server di WhatsApp |
delivered | Arrivato sul dispositivo del destinatario |
read | Letto; solo se l'utente ha attivato le conferme di lettura |
failed | Fallito, con il codice di errore di Meta |
deleted | Messaggio eliminato |
Tentativi e fallimenti
Una consegna è considerata riuscita con qualsiasi 2xx. Qualsiasi altra risposta, compreso un
timeout oltre i 10 secondi, viene ritentata 5 volte con un backoff crescente (1 min, 5 min, 30 min,
2 h, 6 h), poi segnata come fallita.
Log e reinvio
Il portale conserva la cronologia delle consegne: payload, stato HTTP, numero di tentativi e risposta del tuo server. Se qualcosa si è rotto dal tuo lato, puoi reinviare un evento quando il tuo endpoint torna disponibile.
Una chiave API non interviene nella ricezione dei webhook: l'unica cosa da verificare lato ricevente è la firma. Non fidarti mai del contenuto di un evento non firmato.