Guida ai webhook WhatsApp: eventi, sicurezza e nuovi tentativi

{
  "messageId": "2603121407537573731",
  "channel": "SMS",
  "destination": "447700900123",
  "status": "DELIVERED",
  "timestamp": "2026-10-10T09:15:42Z",
  "reason": null
}

Come scrivo un gestore affidabile?

Fate tre cose in ordine: salvate l'evento grezzo, confermate con un 2xx, poi elaborate in modo asincrono. Il gestore qui sotto segue lo schema della nostra documentazione.

import express from "express";

const app = express();

// Catturate il corpo grezzo per memorizzarlo esattamente come ricevuto.
app.post(
  "/webhooks/omnichannels",
  express.json({ verify: (req, _res, buf) => { req.rawBody = buf.toString("utf8"); } }),
  async (req, res) => {
    try {
      await db.webhookEvents.insert({ receivedAt: new Date(), body: req.rawBody });
    } catch (err) {
      return res.sendStatus(500); // salvataggio fallito: lasciate che l'evento venga ritentato
    }
    res.sendStatus(200);          // confermate subito
    queue.publish("status-events", req.body); // il lavoro vero si svolge altrove
  },
);

// Worker: elaborazione idempotente
async function processEvent(event) {
  const id = event.messageId ?? event.message_id ?? event.id; // mappate per canale
  const status = event.status;
  const rank = { SUBMITTED: 1, SENT: 2, DELIVERED: 3, READ: 4, FAILED: 4, REJECTED: 4 };

  const current = await db.messages.findOne({ providerId: id });
  if (!current) return; // messaggio sconosciuto: registratelo e indagate
  if ((rank[status] ?? 0) <= (rank[current.status] ?? 0)) return; // duplicato o evento superato

  await db.messages.update({ providerId: id }, { status, updatedAt: new Date() });
}

from datetime import datetime, timezone
from flask import Flask, request

app = Flask(__name__)

RANK = {"SUBMITTED": 1, "SENT": 2, "DELIVERED": 3, "READ": 4, "FAILED": 4, "REJECTED": 4}


@app.post("/webhooks/omnichannels")
def omnichannels_webhook():
    raw = request.get_data(as_text=True)
    try:
        db.webhook_events.insert({"received_at": datetime.now(timezone.utc), "body": raw})
    except Exception:
        return "", 500           # salvataggio fallito: lasciate che l'evento venga ritentato
    queue.publish("status-events", raw)  # elaborate in modo asincrono
    return "", 200               # confermate subito

Gli oggetti db e queue sono il vostro storage e la vostra coda di job. La mappa rank è ciò che rende idempotente l'elaborazione: un evento duplicato o superato non è un avanzamento, quindi viene ignorato.

Regole per un gestore affidabile

• Rispondete entro pochi secondi. Non svolgete lavoro pesante prima di rispondere.
• Restituite 2xx solo dopo aver salvato l'evento. Se il salvataggio fallisce, restituite 5xx.
• Deduplicate per ID del messaggio. Lo stesso stato può arrivare più di una volta.
• Non reinviate mai un messaggio dal gestore. Decidete i nuovi tentativi in un job separato, dopo aver controllato lo stato.
• Conservate il corpo grezzo per la risoluzione dei problemi e per rielaborare gli eventi dopo una correzione.

Come proteggo un webhook WhatsApp?

Dipende da chi invia al vostro endpoint. Meta firma i webhook che invia alle app registrate presso Meta. La specifica dell'API di OmniChannels.ai non definisce alcun header di firma dei webhook, quindi non aspettatevene uno.

Per lo schema di Meta, la documentazione di Meta indica di generare un hash HMAC-SHA256 dal payload JSON usando il segreto dell'app e di confrontarlo con il valore dopo sha256= nell'header X-Hub-Signature-256. L'HMAC stesso è definito nell'RFC 2104. Calcolatelo sui byte grezzi, non su un oggetto ri-serializzato, e confrontate in tempo costante.

Per il nostro endpoint:

• Usate solo HTTPS, con un certificato valido.
• Usate un percorso lungo e non indovinabile e cambiatelo se trapela.
• Convalidate la forma del corpo e rifiutate tutto ciò che è inatteso.
• Trattate gli eventi come notifiche. Prima di un'azione irreversibile, come un rimborso o un blocco antifrode, confermate lo stato con una chiamata di polling.

Cosa succede quando la consegna fallisce?

I nuovi tentativi dipendono da chi invia. La documentazione di Meta dice che riprova una consegna fallita con frequenza decrescente fino a 7 giorni, il che può produrre notifiche duplicate. È un motivo per essere idempotenti anche se vedete raramente duplicati. Per gli eventi della nostra piattaforma, confermate il comportamento dei nuovi tentativi con il vostro tecnico di attivazione invece di dare per scontato che coincida con quello di Meta.

In ogni caso, costruite sia per la perdita sia per la duplicazione: il vostro endpoint può essere fuori servizio durante un deploy e una regola del firewall può scartare le richieste in silenzio.

Come recupero gli eventi mancanti?

Interrogate il batch, non reinviate il messaggio.

curl "https://api.broadnet.me/whatsapp/message/bulk-insights?batch_Id=2609091405000000001&page=0&size=100" \
  -H "Authorization: Bearer $BROADNET_TOKEN"

batch_Id è l'ID restituito dalla chiamata di invio e page parte da zero. Eseguite una riconciliazione notturna che legge i batch del giorno prima e colma le lacune.

Checklist di risoluzione dei problemi

1. L'URL è configurato sull'account o sul sotto-account giusto?
2. L'endpoint è raggiungibile in HTTPS con un certificato valido?
3. Risponde 2xx rapidamente o va in timeout?
4. Una regola di firewall o WAF blocca le richieste?
5. Registrate il corpo grezzo prima di analizzarlo, così un errore del parser non può nascondere l'evento?

Esempio pratico: la pipeline di notifica di un rivenditore

«Souq Rafiq» (nome di fantasia), un rivenditore degli Emirati, invia aggiornamenti sugli ordini via WhatsApp e vuole uno stato accurato nel proprio strumento di gestione degli ordini.

1. Gli ordini vengono inviati con sendbulk e il batchId viene memorizzato sull'ordine. Vedi inviare un messaggio WhatsApp via API.
2. L'endpoint webhook scrive ogni evento in una tabella, poi restituisce 200.
3. Un worker assegna il rango agli stati e aggiorna lo stato del messaggio dell'ordine.
4. Gli eventi FAILED creano un'attività per l'assistenza con il motivo e si valuta un fallback SMS secondo il fallback tra canali.
5. I messaggi in arrivo dai clienti vengono instradati alla casella condivisa (shared inbox), così gli operatori possono rispondere dentro la finestra.
6. Un job notturno chiama bulk-insights per i batch del giorno prima e corregge ciò che è stato perso.

Quali sono gli errori comuni?

• Lavoro pesante prima di rispondere, che causa timeout e consegne ripetute.
• Confermare prima di salvare, il che fa perdere eventi quando il salvataggio fallisce.
• Fidarsi dell'ordine. Un SENT in ritardo che sovrascrive DELIVERED.
• Scrivere codice basato sul payload illustrativo invece che su eventi reali.
• Ri-serializzare il JSON prima di verificare una firma, il che cambia i byte.
• Reinviare dal gestore, il che può creare cicli.
• Limiti: questa guida descrive il comportamento documentato da noi. Politica dei nuovi tentativi e campi del payload per il vostro account vanno confermati durante l'attivazione.

Come vi aiuta OmniChannels.ai

OmniChannels.ai invia al vostro webhook stati di consegna e messaggi in arrivo per WhatsApp, SMS, RCS e altri canali in un unico formato normalizzato, con webhook separati per sotto-account per i reseller. BroadNet è un Meta Business Solution Provider ufficiale, quindi i requisiti webhook di Meta sono gestiti per voi e voi lavorate con la nostra API. Leggete il riferimento sui webhook e la documentazione dell'API WhatsApp, oppure scoprite come gli eventi compaiono nella casella condivisa.