Genuka WA docs

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:

POST /api/v1/webhooks
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.

POST https://api.example.com/webhooks/genuka
{
  "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:

typeCos'èdata
inbound_messageUn messaggio dal clienteL'oggetto message di Meta
message_statussent, delivered, read o failed per un messaggio che hai inviatoL'oggetto status di Meta
template_statusUn modello è stato approvato, rifiutato o messo in pausaIl valore change di Meta
account_updateUna modifica sul WhatsApp Business AccountIl valore change di Meta
phone_qualityÈ cambiata la qualità o il livello di un numeroIl 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):

data — il cliente ha toccato un pulsante di risposta (messaggio interattivo)
{
  "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.id o data.interactive.list_reply.id, l'id che 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, è il wamid del messaggio a cui il cliente sta rispondendo.

Come leggo uno stato di consegna?

data — message_status in failed
{
  "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?

HeaderContenuto
X-Genuka-Signaturet=<timestamp>,v1=<hex HMAC>
X-Genuka-EventIl type dell'evento
X-Genuka-Event-FieldIl campo webhook di Meta sottostante
X-Genuka-DeliveryL'id della consegna, uguale all'id del corpo, identico tra i tentativi
X-Genuka-Webhook-IdL'endpoint destinatario
X-Genuka-AttemptIl numero del tentativo, a partire da 1
X-Genuka-Testtrue su un evento di test, assente altrimenti

Come verifico la firma HMAC?

L'algoritmo, esattamente come firma Genuka WA:

  1. Leggi il corpo grezzo, prima di qualsiasi JSON.parse.
  2. Da X-Genuka-Signature, leggi t (secondi Unix) e ogni v1 (possono essercene diversi).
  3. Rifiuta se t dista più di 300 secondi dal tuo orologio.
  4. Calcola l'HMAC-SHA256 esadecimale della stringa t + . + corpo grezzo, con chiave il segreto intero, prefisso whsec_ compreso.
  5. 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:

verify-signature.ts
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:

app/api/webhooks/genuka/route.ts
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:

  1. verifica la firma;
  2. salva l'evento, deduplicato sul suo id: un insert, pochi millisecondi;
  3. rispondi 204;
  4. 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.

schema.sql
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
);
save-event-once.ts
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 proprio id. In quel caso deduplica anche sulla chiave di business: data.id (il wamid) per un messaggio in arrivo, la coppia data.id + data.status per uno stato.
  • Gli eventi di test hanno un id che inizia con test_, l'header X-Genuka-Test: true e nessun header X-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:

TentativoQuando
1Appena arriva l'evento
2Almeno 1 minuto dopo il fallimento del precedente
3Almeno 5 minuti dopo
4Almeno 30 minuti dopo
5Almeno 2 ore dopo
6Almeno 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:

Elenca le consegne fallite, poi rigiocane una
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:

POST /api/v1/messages
{
  "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

In questa pagina