# Ricevere risposte e stati WhatsApp via webhook

URL: https://wa.genuka.com/it/docs/guides/receive-messages-webhooks
Language: Italian

> 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?

1. ### 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.

2. ### Registralo

   Nella dashboard in **Webhook**, oppure tramite l'API:

   ```bash title="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.

3. ### 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.

4. ### 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.

```json title="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:

| `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](https://wa.genuka.com/it/docs/webhooks).

### Come leggo la risposta di un cliente?

Il contenuto di un `inbound_message` dipende da `data.type`
([documentazione Meta, incoming messages](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages)):

```json title="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](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/interactive)).
* `type: "button"` → `data.button.payload`: un pulsante di risposta rapida su un modello
  ([documentazione Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/button)).
* `data.context.id`, quando presente, è il `wamid` del messaggio a cui il cliente sta rispondendo.

### Come leggo uno stato di consegna?

```json title="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](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status)).

### 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:

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.

> [!NOTE]
> **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:

```ts title="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:

**Next.js**

```ts title="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 });
}
```

**Express**

```ts title="server.ts"
// Esegui con tsx (`npx tsx server.ts`), che risolve ./verify-signature.js nel file .ts.
import express from "express";
import { verifySignature } from "./verify-signature.js";

const app = express();

// Dichiarata PRIMA di app.use(express.json()): un parser globale consumerebbe il corpo,
// e la firma non corrisponderebbe mai.
app.post("/webhooks/genuka", express.raw({ type: "application/json" }), async (req, res) => {
  const raw = req.body.toString("utf8");
  const signature = req.get("X-Genuka-Signature") ?? null;
  if (!verifySignature(raw, signature, process.env.GENUKA_WEBHOOK_SECRET!)) {
    return res.status(401).send("invalid signature");
  }
  // Un evento di test è firmato come uno reale: non deve scrivere nulla nel tuo database.
  if (req.get("X-Genuka-Test") === "true") return res.sendStatus(204);

  const event = JSON.parse(raw);
  const fresh = await saveEventOnce(event); // INSERT … ON CONFLICT (id) DO NOTHING
  res.sendStatus(204); // prima rispondi
  if (fresh) await queue.add("genuka-event", event); // poi elabora, fuori dalla richiesta
});

app.use(express.json()); // il resto della tua API
```

**Python (Flask)**

```python title="app.py"
import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request

app = Flask(__name__)
SECRET = os.environ["GENUKA_WEBHOOK_SECRET"].encode()  # il segreto intero, prefisso whsec_ compreso
TOLERANCE_SECONDS = 300


def verify_signature(raw, header):
    if not header:
        return False
    timestamp, signatures = None, []
    for part in header.split(","):
        key, _, value = part.partition("=")
        key, value = key.strip(), value.strip()
        # isascii(): isdigit() da solo accetta "²", su cui int() solleva un'eccezione.
        if key == "t" and value.isascii() and value.isdigit():
            timestamp = int(value)
        elif key == "v1" and value:
            signatures.append(value)
    if timestamp is None or not signatures:
        return False
    # Il timestamp fa parte dell'HMAC: fuori dalla finestra, una richiesta catturata non vale nulla.
    if abs(time.time() - timestamp) > TOLERANCE_SECONDS:
        return False
    expected = hmac.new(SECRET, f"{timestamp}.".encode() + raw, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(s.encode(), expected.encode()) for s in signatures)


@app.post("/webhooks/genuka")
def genuka_webhook():
    raw = request.get_data()  # i byte ricevuti, prima di qualsiasi parsing
    if not verify_signature(raw, request.headers.get("X-Genuka-Signature")):
        abort(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 "", 204

    event = json.loads(raw)
    if save_event_once(event):  # INSERT … ON CONFLICT (id) DO NOTHING
        enqueue(event)  # Celery, RQ…: l'elaborazione non trattiene la risposta
    return "", 204
```

**@genuka/whatsapp**

```ts title="app/api/webhooks/genuka/route.ts"
import { verifySignature } from "@genuka/whatsapp/webhooks";

export async function POST(request: Request) {
  const raw = await request.text();
  const ok = await verifySignature(
    process.env.GENUKA_WEBHOOK_SECRET!,
    raw,
    request.headers.get("x-genuka-signature"),
  );
  if (!ok) return new Response("invalid signature", { status: 401 });

  // … da qui in poi, come nella scheda Next.js
  return new Response(null, { status: 204 });
}
```

Il `verifySignature` della [libreria](https://wa.genuka.com/it/docs/library) è asincrono (WebCrypto, quindi gira anche su
un runtime edge) e richiede `@genuka/whatsapp` 0.1.1 o successivo.

## 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.

```sql title="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
);
```

```ts title="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](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status)).
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:

```bash title="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](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages)).
Riusa il `connection_id` dell'evento, metti un `+` davanti a `data.from` e cita il messaggio con
`replyTo`:

```json title="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](https://wa.genuka.com/it/docs/guides/order-notifications).

## 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

* [Meta — Messages webhook reference](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages)
* [Meta — Interactive message replies](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/interactive)
* [Meta — Button message replies](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/button)
* [Meta — Status messages webhook](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status)
* [Meta — Send messages (customer service window)](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages)
