Ricevere risposte e stati WhatsApp via webhook
Ricevi sul tuo server le risposte WhatsApp e gli stati di consegna: registra un webhook, verifica la firma HMAC, deduplica, gestisci i nuovi tentativi e il replay.
Per ricevere le risposte WhatsApp e gli stati di consegna, registra un URL HTTPS in Genuka WA: ogni
evento vi arriva come POST firmato. Il tuo endpoint verifica la firma HMAC-SHA256 nell'header
X-Genuka-Signature sul corpo grezzo, salva l'evento una sola volta tramite il suo id, risponde
2xx entro 10 secondi, poi lo elabora in background.
Ultimo aggiornamento: 8 ottobre 2026
Come registro un endpoint webhook?
Esponi un URL HTTPS pubblico
Genuka WA rifiuta gli URL http://, gli URL che contengono nome utente e password e gli URL che
puntano a un indirizzo privato o locale. Per sviluppare sulla tua macchina, passa da un tunnel
HTTPS. I redirect non vengono seguiti: una risposta 3xx conta come errore, quindi registra l'URL
finale esatto.
Registralo
Nella dashboard in Webhook, oppure tramite l'API:
curl -X POST https://wa.genuka.com/api/v1/webhooks \
-H "Authorization: Bearer $GENUKA_WA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.example.com/webhooks/genuka",
"connectionId": "con_1",
"events": ["message.received", "message.sent", "message.delivered", "message.read",
"message.failed", "template.status_changed"]
}'Senza connectionId né companyId, l'endpoint copre tutti i numeri che la tua chiave può
raggiungere. Un events vuoto o assente significa "tutti gli eventi". template.status_changed
porta il verdetto di Meta sui tuoi modelli (l'evento template_status): senza, un endpoint iscritto
solo ai messaggi non lo riceve mai.
Copia il segreto
La risposta 201 contiene secret (whsec_…). Viene restituito solo alla creazione e alla
rotazione (PATCH /api/v1/webhooks/{id} con "rotateSecret": true): salvalo nel tuo ambiente, per
esempio come GENUKA_WEBHOOK_SECRET. Una rotazione ha effetto immediato.
Testalo
POST /api/v1/webhooks/{id}/test invia al tuo URL un esempio per ogni famiglia di eventi e
restituisce lo stato HTTP ottenuto per ciascuno. Gli esempi sono firmati con il tuo segreto, come
una consegna reale: è così che testi la verifica della firma prima del primo messaggio vero.
Com'è fatto un evento?
Ogni consegna è un POST JSON che contiene un evento. I campi intorno a data ti dicono a quale
azienda e a quale numero appartiene; connection_id è quello da riusare quando rispondi.
{
"id": "cmg7v2k0x0001…",
"type": "inbound_message",
"field": "messages",
"created_at": "2026-10-08T09:31:07.412Z",
"partner_id": "cl9x…",
"company_id": "cm31…",
"connection_id": "cn77…",
"waba_id": "102290129340398",
"phone_number_id": "106540352242922",
"data": {
"from": "237699001122",
"id": "wamid.HBgLMjM3…",
"timestamp": "1791451865",
"type": "text",
"text": { "body": "Domani non sarò a casa" }
}
}Per i cinque tipi storici, data è l'oggetto grezzo inviato da Meta, intatto:
type | Cos'è | data |
|---|---|---|
inbound_message | Un messaggio dal cliente | L'oggetto message di Meta |
message_status | sent, delivered, read o failed per un messaggio che hai inviato | L'oggetto status di Meta |
template_status | Un modello è stato approvato, rifiutato o messo in pausa | Il valore change di Meta |
account_update | Una modifica sul WhatsApp Business Account | Il valore change di Meta |
phone_quality | È cambiata la qualità o il livello di un numero | Il valore change di Meta |
Gli eventi più recenti hanno un nome Genuka (user_preference.stopped, template.quality_changed,
unknown.received…) e un data normalizzato. Fai sempre lo switch su type, e ignora senza errori
ciò che non gestisci: possono comparire nuovi tipi. Vedi anche il
riferimento dei Webhook.
Come leggo la risposta di un cliente?
Il contenuto di un inbound_message dipende da data.type
(documentazione Meta, incoming messages):
{
"context": { "from": "237690000000", "id": "wamid.of_the_message_you_sent…" },
"from": "237699001122",
"id": "wamid.HBgL…",
"timestamp": "1791451865",
"type": "interactive",
"interactive": { "type": "button_reply", "button_reply": { "id": "yes", "title": "Conferma" } }
}type: "text"→data.text.body.type: "interactive"→data.interactive.button_reply.idodata.interactive.list_reply.id, l'idche hai dato al pulsante o alla riga (documentazione Meta).type: "button"→data.button.payload: un pulsante di risposta rapida su un modello (documentazione Meta).data.context.id, quando presente, è ilwamiddel messaggio a cui il cliente sta rispondendo.
Come leggo uno stato di consegna?
{
"id": "wamid.HBgLMjM3…",
"status": "failed",
"timestamp": "1791451901",
"recipient_id": "237699001122",
"errors": [{ "code": 131026, "title": "…" }]
}data.id è il messageId restituito da POST /api/v1/messages. errors compare solo in caso di
errore (documentazione Meta, statuses).
Quali header accompagnano ogni consegna?
| Header | Contenuto |
|---|---|
X-Genuka-Signature | t=<timestamp>,v1=<hex HMAC> |
X-Genuka-Event | Il type dell'evento |
X-Genuka-Event-Field | Il campo webhook di Meta sottostante |
X-Genuka-Delivery | L'id della consegna, uguale all'id del corpo, identico tra i tentativi |
X-Genuka-Webhook-Id | L'endpoint destinatario |
X-Genuka-Attempt | Il numero del tentativo, a partire da 1 |
X-Genuka-Test | true su un evento di test, assente altrimenti |
Come verifico la firma HMAC?
L'algoritmo, esattamente come firma Genuka WA:
- Leggi il corpo grezzo, prima di qualsiasi
JSON.parse. - Da
X-Genuka-Signature, leggit(secondi Unix) e ogniv1(possono essercene diversi). - Rifiuta se
tdista più di 300 secondi dal tuo orologio. - Calcola l'HMAC-SHA256 esadecimale della stringa
t+.+ corpo grezzo, con chiave il segreto intero, prefissowhsec_compreso. - Accetta se uno dei valori
v1è uguale, confrontato a tempo costante.
Una riconsegna tardiva passa comunque la finestra
Ogni tentativo viene firmato alla partenza, con un t nuovo. Un nuovo tentativo sei ore dopo, o un
replay manuale, viene quindi accettato dalla tolleranza di 300 secondi; una richiesta catturata e
riprodotta da un terzo no, perché t non si può modificare senza invalidare v1.
La funzione di verifica, senza dipendenze:
import crypto from "node:crypto";
const TOLERANCE_SECONDS = 300;
export function verifySignature(rawBody: string, header: string | null, secret: string): boolean {
if (!header) return false;
let timestamp = Number.NaN;
const signatures: string[] = [];
for (const part of header.split(",")) {
const [key, value] = part.split("=", 2).map((s) => s.trim());
if (key === "t") timestamp = Number(value);
if (key === "v1" && value) signatures.push(value);
}
if (!Number.isFinite(timestamp) || signatures.length === 0) return false;
// Il timestamp fa parte dell'HMAC: fuori dalla finestra, una richiesta catturata non vale nulla.
if (Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) return false;
const expected = crypto
.createHmac("sha256", secret) // il segreto intero, prefisso whsec_ compreso
.update(`${timestamp}.${rawBody}`)
.digest("hex");
// timingSafeEqual lancia un'eccezione su due buffer di lunghezza in byte diversa, e l'header lo
// scrive chi invia la richiesta: confronta le lunghezze in byte, non quelle delle stringhe ("é" è
// un carattere ma due byte), altrimenti un header contraffatto trasforma un 401 in un 500.
const expectedBytes = Buffer.from(expected);
return signatures.some((candidate) => {
const candidateBytes = Buffer.from(candidate);
return (
candidateBytes.length === expectedBytes.length &&
crypto.timingSafeEqual(candidateBytes, expectedBytes)
);
});
}Poi l'endpoint, per il tuo framework:
import { after } from "next/server";
import { verifySignature } from "@/lib/verify-signature";
export async function POST(request: Request) {
const raw = await request.text(); // il corpo esattamente come è stato firmato
const signature = request.headers.get("x-genuka-signature");
if (!verifySignature(raw, signature, process.env.GENUKA_WEBHOOK_SECRET!)) {
return new Response("invalid signature", { status: 401 });
}
// Un evento di test è firmato come uno reale: non deve scrivere nulla nel tuo database.
if (request.headers.get("x-genuka-test") === "true") return new Response(null, { status: 204 });
const event = JSON.parse(raw);
// Prima salva (veloce, deduplicato su event.id), poi elabora dopo la risposta.
const fresh = await saveEventOnce(event);
if (fresh) after(() => processEvent(event));
return new Response(null, { status: 204 });
}Come rispondo abbastanza in fretta da evitare le riconsegne?
Una consegna riesce con qualsiasi 2xx. Tutto il resto fallisce e verrà ritentato: uno stato 4xx o
5xx, un redirect o una risposta che impiega più di 10 secondi.
La sequenza che regge sotto carico:
- verifica la firma;
- salva l'evento, deduplicato sul suo
id: un insert, pochi millisecondi; - rispondi
204; - elabora dopo, in
after(), in una coda di job o in un worker.
Rispondi 5xx solo se è fallito il salvataggio stesso: è l'unico caso in cui ti serve che Genuka WA
riprovi. Un'elaborazione che fallisce dopo la risposta si rigioca dalla tua tabella, non dal webhook.
Come deduplico gli eventi?
L'id del corpo, uguale all'header X-Genuka-Delivery, è identico tra i tentativi e in un replay
manuale. È la tua chiave di idempotenza.
create table genuka_events (
id text primary key, -- l'id del corpo, stabile tra i tentativi
type text not null,
payload jsonb not null,
received_at timestamptz not null default now(),
processed_at timestamptz -- null finché l'elaborazione non riesce
);export async function saveEventOnce(event: { id: string; type: string }): Promise<boolean> {
const result = await db.query(
"insert into genuka_events (id, type, payload) values ($1, $2, $3) on conflict (id) do nothing",
[event.id, event.type, JSON.stringify(event)],
);
return result.rowCount === 1; // false: già ricevuto, niente da fare
}Altri due punti:
- Più endpoint, più
id. Se due tuoi endpoint coprono lo stesso numero, ognuno riceve la propria consegna, con il proprioid. In quel caso deduplica anche sulla chiave di business:data.id(ilwamid) per un messaggio in arrivo, la coppiadata.id+data.statusper uno stato. - Gli eventi di test hanno un
idche inizia contest_, l'headerX-Genuka-Test: truee nessun headerX-Genuka-Delivery. Filtrali prima di scrivere qualsiasi cosa nel tuo database, come fanno gli esempi qui sopra.
Infine, l'ordine non è garantito: un read può arrivare prima del delivered dello stesso
messaggio, e delivered può anche non arrivare mai. Quando il cliente ha la chat aperta nel momento
in cui arriva il messaggio, Meta lo considera consegnato e letto insieme e invia solo read
(documentazione Meta, statuses).
Quindi tratta read come se implicasse delivered, e non far mai tornare indietro uno stato:
sent → delivered → read, e failed è definitivo.
Cosa succede se il mio server è giù?
Genuka WA fa fino a sei tentativi in tutto:
| Tentativo | Quando |
|---|---|
| 1 | Appena arriva l'evento |
| 2 | Almeno 1 minuto dopo il fallimento del precedente |
| 3 | Almeno 5 minuti dopo |
| 4 | Almeno 30 minuti dopo |
| 5 | Almeno 2 ore dopo |
| 6 | Almeno 6 ore dopo, poi la consegna viene marcata failed |
I nuovi tentativi partono da una coda svuotata ogni 10 minuti, quindi un tentativo può arrivare fino a circa dieci minuti dopo il suo ritardo minimo, di più sotto un forte arretrato.
Quando il tuo endpoint torna su, trova cosa è fallito e rigiocalo:
curl "https://wa.genuka.com/api/v1/webhooks/wh_1/deliveries?status=failed" \
-H "Authorization: Bearer $GENUKA_WA_API_KEY"
curl -X POST https://wa.genuka.com/api/v1/webhooks/wh_1/deliveries/cmg7v2k0x0001/replay \
-H "Authorization: Bearer $GENUKA_WA_API_KEY"Il replay risponde 202 e riparte con un nuovo budget di tentativi. Una consegna ancora pending
viene rifiutata (409 delivery_pending): è già in coda. Il log conserva il corpo esatto di ogni
consegna; per quanto tempo dipende dal tuo piano ed è indicato in meta.retentionDays. La sezione
Webhook della dashboard offre lo stesso log e lo stesso pulsante di reinvio.
Come rispondo a un messaggio ricevuto?
Finché il cliente ti ha scritto nelle ultime 24 ore, puoi rispondere con testo libero
(documentazione Meta).
Riusa il connection_id dell'evento, metti un + davanti a data.from e cita il messaggio con
replyTo:
{
"connectionId": "cn77…",
"to": "+237699001122",
"replyTo": "wamid.HBgLMjM3…",
"text": "Grazie, ricevuto!"
}Per mostrare le spunte blu, chiama POST /api/v1/messages/{wamid}/read con { "connectionId": … }
nel corpo, con il wamid codificato per URL. Fuori dalla finestra ti serve un modello: vedi
Notifiche d'ordine.
FAQ
Perché la mia firma non corrisponde mai?
Quasi sempre una di quattro cause: il corpo è stato parsato e riserializzato prima della verifica
(un express.json() globale, per esempio); il segreto è stato copiato senza il prefisso whsec_;
l'orologio del server sfasa di più di cinque minuti; oppure il segreto è stato ruotato nel frattempo.
Posso ricevere direttamente i webhook di Meta?
No. I webhook della Cloud API arrivano a Genuka WA, che te li inoltra firmati con il tuo segreto. Per
i cinque tipi storici, data resta l'oggetto originale di Meta: il codice che legge già il formato di
Meta si trova a casa.
Mi serve una chiave API per ricevere i webhook?
No. L'unica cosa da verificare lato ricezione è la firma. Non elaborare mai un evento non firmato.
Gli stati arrivano in ordine?
No: read può arrivare prima di delivered, o anche da solo. Ordina gli stati per rango, tratta
read come se implicasse delivered e non farli mai tornare indietro.
Fonti
Inviare una campagna WhatsApp tramite l'API
Invia una campagna WhatsApp tramite l'API: modello marketing, destinatari, lancio, quote del piano, limiti marketing di Meta e tracciamento delle consegne.
Coesistenza: API WhatsApp e app Business
Tieni l'app WhatsApp Business sul tuo numero mentre usi l'API: requisiti (2.24.17+), passaggi di onboarding, cosa si sincronizza e i limiti.