# Webhook

URL: https://wa.genuka.com/it/docs/webhooks
Language: Italian

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

```json title="POST https://your-app.com/webhooks/whatsapp"
{
  "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`.

> [!WARNING]
> 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.

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

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

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

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

> [!WARNING]
> **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.

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