Genuka WA docs

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

EventoContenuto
messagesMessaggi in arrivo e stati dei messaggi che hai inviato
message_template_status_updateUn modello è stato approvato, rifiutato o messo in pausa
account_updateModifica dell'account: verifica, restrizione, sospensione
phone_number_quality_updateÈ cambiata la qualità o il livello di invio di un numero
connection.connectedUn numero è appena stato collegato tramite il tuo link, con il tuo ref (vedi Collegare un numero)
call.connect · call.status_changed · call.terminatedChiamate 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_repliedUn 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.

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"
  }
}
HeaderContenuto
X-Genuka-SignatureLa firma (vedi sotto)
X-Genuka-EventTipo di evento, per esempio message_status
X-Genuka-Event-FieldIl campo webhook di Meta sottostante, oppure il nome dell'evento quando non proviene da Meta
X-Genuka-DeliveryId della consegna, identico tra i tentativi: usalo per eliminare i duplicati
X-Genuka-Webhook-IdL'endpoint destinatario
X-Genuka-AttemptNumero 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:

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

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

StatoSignificato
sentAccettato dai server di WhatsApp
deliveredArrivato sul dispositivo del destinatario
readLetto; solo se l'utente ha attivato le conferme di lettura
failedFallito, con il codice di errore di Meta
deletedMessaggio 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.

In questa pagina