AccediInizia la prova gratuita
Meta Tech Provider

Come arrivano i messaggi WhatsApp al tuo server: diretti o gestiti, e come verificare la firma

Ogni numero collegato tramite easyCoexistence ha una sola modalità di ricezione. Direttamente al tuo sistema (diretto): Meta invia i suoi webhook al tuo endpoint HTTPS, un segreto nell'URL funge da credenziale e le automazioni sono disattivate. Tramite easyCoexistence (gestito): Meta consegna a easyCoexistence, le automazioni possono rispondere e un Forward URL facoltativo riceve il valore originale di Meta con i dettagli della connessione, firmato con X-EC-Signature perché tu lo verifichi.

7 attempts

Tentativi per ogni consegna inoltrata, distanziati di 1 min, 5 min, 30 min, 2 h, 6 h e 24 h, circa 33 ore in totale.

10 s

Quanto attende ogni tentativo di inoltro una risposta 2xx prima di essere considerato fallito.

5 min

Limite consigliato sull'età del t della firma; i nuovi tentativi vengono firmati di nuovo, quindi le consegne genuine restano entro il limite.

7 days

Per quanto tempo Meta ritenta un webhook diretto che ha ricevuto qualsiasi cosa diversa da HTTP 200, con possibili messaggi ripetuti.

3 MB

Il payload webhook più grande che Meta invia, blocchi della cronologia inclusi.

30 days

Log di esecuzione conservati per un numero gestito, con testo dei messaggi e delle risposte; il testo dei messaggi stesso è conservato 30, 90 o 365 giorni, a tua scelta.

Qual è la differenza tra diretto e gestito?

Indica dove Meta consegna i webhook dei messaggi del numero. Gestito, indicato come Tramite easyCoexistence, significa che Meta consegna a easyCoexistence, che verifica la firma di Meta, esegue le tue automazioni, conserva le chat per Conversazioni e, se imposti un Forward URL, ti inoltra ogni modifica di Meta firmata con un segreto che solo tu conosci. Diretto, indicato come Direttamente al tuo sistema, significa che easyCoexistence imposta il tuo endpoint HTTPS come override del webhook sul WhatsApp Business Account del numero, quindi Meta ti invia i dati direttamente e i messaggi non passano mai da easyCoexistence.

I webhook operativi alla base del monitoraggio, come account_update e le variazioni di qualità, restano con easyCoexistence in entrambe le modalità, per questo gli avvisi continuano a funzionare in ogni caso.

Managed: Through easyCoexistenceDirect: Straight to your system
Meta delivers toeasyCoexistence, which verifies Meta's signatureYour HTTPS endpoint
AutomationsRun on the numberOff
Your copyOptional Forward URL, one Meta change per POSTMeta's envelope, unchanged
Proof it is genuineX-EC-Signature, HMAC-SHA256 with the number's secretA long random secret in the URL path
Failed deliveries7 attempts over about 33 hoursMeta retries for up to 7 days
History importNot requestedRequested when saved within 24 hours of connecting
Kept by easyCoexistenceMessage text 30, 90 or 365 days, run logs 30 daysNothing

Come si passa un numero da una modalità all'altra?

Nella pagina del numero, la scheda Dove vanno i messaggi in ingresso mostra la modalità come due scelte, Tramite easyCoexistence e Direttamente al tuo sistema. Salvare una destinazione webhook, nella scheda Invia i messaggi in ingresso al tuo webhook oppure con set_webhook_destination, rende il numero diretto. Scegliere Tramite easyCoexistence rimuove subito quella destinazione presso Meta, quindi aggiungi lo stesso URL come Forward URL per continuare a ricevere. Gli inoltri in coda vengono eliminati quando un numero esce dalla modalità gestita, e i numeri collegati senza URL webhook partono in modalità gestita.

Dalla tua AI, set_inbound_mode cambia la modalità e imposta l'inoltro in un'unica chiamata, e restituisce il segreto dell'inoltro una sola volta:

set_inbound_mode: arguments and result
// set_inbound_mode arguments
{
  "connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
  "mode": "managed",
  "forward_url": "https://agent.example.com/ec/forward"
}

// result: forward_secret is shown once
{
  "connection_id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
  "mode": "managed",
  "forward_url": "https://agent.example.com/ec/forward",
  "forward_secret": "whsec_Qm9vbXRoZXNlY3JldHNhcmVmYWtlMTIz",
  "secret_note": "Shown once. Verify X-EC-Signature: t=<unix>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\"> with it; the body's value is Meta's original payload.",
  "direct_destination": null
}

Cosa contiene un POST inoltrato?

Una modifica di Meta per richiesta, incapsulata, anziché la struttura object, entry e changes di Meta. id è l'ID della consegna, ripetuto in X-EC-Delivery e stabile tra i tentativi. event è il nome del campo di Meta, messages, smb_message_echoes, history o smb_app_state_sync, ripetuto in X-EC-Event. received_at è il momento in cui easyCoexistence ha ricevuto la modifica da Meta, connection identifica il numero e value è esattamente ciò che Meta ha inviato, quindi il codice di parsing scritto per il payload di Meta funziona anche su questo. Gli stati di consegna arrivano dentro gli eventi messages, sotto value.statuses.

A forwarded messages event: headers and body
POST /ec/forward HTTP/1.1
Content-Type: application/json
User-Agent: easyCoexistence-forward/1
X-EC-Event: messages
X-EC-Delivery: 8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13
X-EC-Signature: t=1794405732,v1=<64 hex characters>

{
  "id": "8c1d7e52-0f4b-4a3e-9d61-2b7f5a9e0c13",
  "event": "messages",
  "received_at": "2026-11-11T14:02:11.482Z",
  "connection": {
    "id": "3f2a9c1e-7b4d-4e8a-9c2f-1a2b3c4d5e6f",
    "phone": "+1 631-555-0142",
    "phone_number_id": "106540352242922",
    "waba_id": "102290129340398",
    "external_ref": null
  },
  "value": {
    "messaging_product": "whatsapp",
    "metadata": { "display_phone_number": "16315550142", "phone_number_id": "106540352242922" },
    "contacts": [{ "profile": { "name": "Ana Souza" }, "wa_id": "5511987654321", "user_id": "BR.13491208655302741918" }],
    "messages": [{
      "from": "5511987654321",
      "from_user_id": "BR.13491208655302741918",
      "id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFjNFQjBDNzE4RjQ2QjI5RDkxQTNFAA==",
      "timestamp": "1794405731",
      "type": "text",
      "text": { "body": "Do you deliver on Sundays?" }
    }]
  }
}

Come si verifica X-EC-Signature in Node.js?

Leggi l'intestazione come t=<secondi unix>,v1=<64 caratteri esadecimali>. Rifiuta un t che differisce più di 5 minuti dal tuo orologio, calcola HMAC-SHA256 su t, un punto e il corpo grezzo, con chiave l'intero segreto dell'inoltro come testo UTF-8, e confronta il risultato con v1 in tempo costante. Solo allora analizza il JSON. Rispondi 2xx entro 10 secondi e svolgi il lavoro dopo, e ricorda gli ID delle consegne che hai accettato, così un nuovo tentativo non viene elaborato due volte.

forward-receiver.mjs (Node.js, no dependencies)
// forward-receiver.mjs: node forward-receiver.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";

const SECRET = process.env.EC_FORWARD_SECRET; // the whole whsec_... string is the HMAC key
const taken = new Set(); // delivery ids already accepted: use a database in production

export function verifyEcSignature(raw, header, secret = SECRET, maxAgeSec = 300) {
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(String(header ?? "").trim());
  if (!m || !secret) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - Number(m[1])) > maxAgeSec) return false;
  const mac = crypto.createHmac("sha256", secret).update(`${m[1]}.`).update(raw).digest();
  return crypto.timingSafeEqual(mac, Buffer.from(m[2], "hex"));
}

http.createServer((req, res) => {
  const chunks = [];
  req.on("data", (c) => chunks.push(c));
  req.on("end", () => {
    const raw = Buffer.concat(chunks);
    if (req.method !== "POST" || !verifyEcSignature(raw, req.headers["x-ec-signature"])) {
      res.writeHead(401).end();
      return;
    }
    res.writeHead(200).end(); // a 2xx within 10 s, before any work
    const d = JSON.parse(raw.toString("utf8"));
    if (taken.has(d.id)) return; // a retry of a delivery already accepted
    taken.add(d.id);
    // d.event is the Meta field (messages, smb_message_echoes, history, smb_app_state_sync)
    // d.value is Meta's change value, unchanged; queue it for your worker here.
    console.log(d.event, d.connection.phone_number_id, Object.keys(d.value));
  });
}).listen(process.env.PORT ?? 3000);

Come si verifica in Python?

Le stesse quattro verifiche con la libreria standard: un pattern rigoroso per l'intestazione, l'età di t, hmac.new su t, un punto e i byte grezzi, e hmac.compare_digest. In FastAPI il corpo grezzo viene da await request.body(), e BackgroundTasks esegue il lavoro dopo l'invio del 200. In Flask usa request.get_data(), e non ricostruire mai il corpo con json.dumps, perché i separatori predefiniti di Python aggiungono spazi e la firma non corrisponde più.

forward_receiver.py (FastAPI)
# forward_receiver.py: pip install fastapi uvicorn, then uvicorn forward_receiver:app
import hashlib, hmac, json, os, re, time
from fastapi import BackgroundTasks, FastAPI, Request, Response

app = FastAPI()
SECRET = os.environ["EC_FORWARD_SECRET"].encode()  # the whole whsec_... string, as bytes
SIGNATURE = re.compile(r"t=([0-9]+),v1=([0-9a-f]{64})")
taken = set()  # delivery ids already accepted: use a database in production

def verify_ec_signature(raw: bytes, header: str, max_age: int = 300) -> bool:
    m = SIGNATURE.fullmatch(header.strip())
    if not m or abs(int(time.time()) - int(m[1])) > max_age:
        return False
    mac = hmac.new(SECRET, m[1].encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(mac, m[2])

def process(delivery: dict) -> None:
    if delivery["id"] in taken:  # a retry of a delivery already accepted
        return
    taken.add(delivery["id"])
    print(delivery["event"], delivery["connection"]["phone_number_id"], list(delivery["value"]))

@app.post("/ec/forward")
async def forward(request: Request, tasks: BackgroundTasks):
    raw = await request.body()
    if not verify_ec_signature(raw, request.headers.get("x-ec-signature", "")):
        return Response(status_code=401)
    tasks.add_task(process, json.loads(raw))  # runs after the 200 goes out
    return Response(status_code=200)

Come vengono ritentate le consegne fallite?

Un inoltro è considerato consegnato quando il tuo endpoint risponde con un qualsiasi 2xx entro 10 secondi. Qualsiasi altra risposta, un timeout, un 4xx, un 5xx o un reindirizzamento, che non viene seguito, pianifica il tentativo successivo circa 1 minuto, 5 minuti, 30 minuti, 2 ore, 6 ore e 24 ore dopo, e dopo il settimo tentativo la consegna viene abbandonata. Ogni tentativo viene firmato di nuovo con un nuovo t, e l'URL deve essere HTTPS pubblico, verificato al salvataggio e di nuovo prima di ogni invio. Le consegne partono dalla più vecchia, ma una consegna ritentata può arrivare dopo quelle più recenti, quindi ordina in base ai timestamp di Meta.

Su una destinazione diretta è Meta a riprovare: qualsiasi risposta diversa da HTTP 200 viene ritentata con frequenza decrescente per fino a 7 giorni, e questi tentativi possono ripetere un messaggio. Deduplica sull'ID messaggio di Meta in entrambe le modalità, perché una modifica che Meta ri-consegna viene inoltrata di nuovo con un nuovo ID di consegna.

Come fa un endpoint diretto a sapere che un POST è genuino?

Non dall'intestazione X-Hub-Signature-256. Meta firma con l'app secret dell'app che possiede la sottoscrizione, che per un numero collegato qui è quella di easyCoexistence e non è condivisa, quindi verificare quell'intestazione con l'app secret della tua app Meta rifiuta le consegne genuine. Il verify token prova l'endpoint una sola volta, durante l'handshake GET di Meta. Funziona invece:

  • Inserisci 32 o più caratteri casuali nel percorso dell'URL di callback e rifiuta le richieste che non li contengono; per ruotarli, salva un nuovo URL.
  • Usa un ricevitore generico, come il nodo Webhook di n8n, non un trigger WhatsApp che si aspetta la tua app Meta.
  • Scarica i media per ID da Meta con il token del numero, così un ID falsificato semplicemente fallisce.
  • Sui server self-hosted, facoltativamente consenti solo la rete di Meta, cioè le route annunciate da AS32934.
  • Oppure passa alla modalità gestita con un Forward URL, dove X-EC-Signature prova ogni POST.

Errori comuni

  • Puntare al Forward URL il codice scritto per l'envelope di Meta senza modifiche. Un inoltro contiene una sola modifica: leggi event e value, non object, entry e changes.
  • Aspettarsi un X-EC-Event di statuses. Gli stati di consegna arrivano dentro gli eventi messages, in value.statuses, e le risposte scritte nell'app arrivano come smb_message_echoes.
  • Elaborare il lavoro prima di rispondere. Un inoltro attende 10 secondi, poi la stessa consegna torna con un nuovo t; rispondi prima con 2xx ed elabora dalla coda.
  • Passare alla modalità gestita pensando che il vecchio URL riceva ancora. La destinazione diretta viene rimossa in quel momento; passa forward_url nella stessa chiamata a set_inbound_mode.
Farlo con EasyCoexistence

easyCoexistence collega un numero dell'app WhatsApp Business alla Cloud API di Meta tramite Coexistence e ti permette di scegliere, per ogni numero, dove vanno i suoi messaggi: direttamente da Meta al tuo server, oppure passando da easyCoexistence, così le automazioni possono rispondere e una copia firmata arriva al tuo Forward URL. Monitoraggio e avvisi funzionano in entrambe le modalità. Da US$ 9 fino a US$ 0,75 per numero al mese, in calo man mano che aggiungi numeri, con i primi 3 giorni di prova gratuita.

Domande frequenti

Il mio server vede cosa ha risposto un'automazione?

Non il testo. Meta segnala gli invii dell'API come stati (inviato, consegnato, letto) dentro gli eventi messages, con l'ID del messaggio; il testo stesso è nel log di esecuzione dell'automazione, conservato 30 giorni nella scheda Esecuzioni, e in Conversazioni per il periodo che hai scelto.

Come ruoto il segreto del Forward?

Clicca Nuovo segreto nella pagina del numero, oppure chiama set_inbound_mode con rotate_secret impostato su true. Il nuovo segreto viene mostrato una sola volta e firma tutto da quel momento in poi, compresi i tentativi delle consegne più vecchie, quindi aggiorna subito il tuo server.

Un Forward URL richiede l'handshake GET di Meta?

No. Solo una destinazione diretta viene chiamata da Meta e deve rispecchiare hub.challenge. Un Forward URL viene chiamato da easyCoexistence e riceve solo POST firmati.

Un numero può avere insieme una destinazione diretta e un Forward URL?

No. Un Forward URL funziona solo mentre il numero è gestito, e salvare una destinazione diretta lo rende diretto. Il Forward URL e il suo segreto vengono conservati, quindi tornare alla modalità gestita riprende l'inoltro.

Continua a leggere

Pronto per iniziare?

Configura WhatsApp Coexistence in pochi minuti, non in mesi. L'app continua a funzionare sul telefono.

Inizia la prova gratuita

Verificato il