AccediInizia la prova gratuita
easyCoexistence API ufficiali

Come ricevere via webhook i messaggi WhatsApp e i commenti social dei tuoi clienti

Ogni connessione ottiene il proprio webhook per i messaggi WhatsApp dei tuoi clienti o per i commenti social, tramite la Partner API di easyCoexistence. I messaggi WhatsApp vanno da Meta direttamente a quell'URL, firmati con il segreto dell'app Tech Provider e non con uno che tu possiedi, quindi un segreto lungo e casuale nel percorso dell'URL li autentica. I commenti e i DM di Instagram e Facebook, e i commenti di TikTok, sono inoltrati appena arrivano, firmati per account con X-EC-Signature.

200 characters

Lunghezza massima che Meta consente per l'URL di callback alternativo che invia i messaggi di un numero al tuo endpoint.

7 days

Per quanto tempo Meta riprova un webhook WhatsApp che il tuo endpoint non ha accettato, con frequenza decrescente, il che può produrre duplicati.

AS32934

La rete di Meta; le ricerche whois sulle rotte per quella rete elencano gli indirizzi da cui arrivano i webhook WhatsApp, che Meta cambia periodicamente.

3 MB

La dimensione massima di un payload di webhook WhatsApp, secondo Meta.

5 minutes

Età oltre la quale un timestamp firmato di un evento inoltrato va rifiutato, con l'HMAC confrontato in tempo costante.

Come ottiene ogni connessione la propria destinazione?

Con una chiamata per risorsa. Un numero WhatsApp usa PUT /connections/{id}/webhook con url e verify_token, oppure la stessa coppia come webhook_url e webhook_verify_token nella sessione di connessione, così il numero ti viene instradato dal primo minuto. Un account social usa PUT /channels/{id}/webhook una volta connesso. Un url null su entrambi disattiva la consegna. I due percorsi differiscono per chi consegna e per come autentichi:

WhatsApp numberInstagram, Facebook, TikTok
Set withwebhook_url on the session, or PUT /connections/{id}/webhookPUT /channels/{id}/webhook, after it connects
Delivered byMeta, straight to your URLeasyCoexistence, forwarding each event as it arrives
BodyMeta's webhook, unchangedplatform, account_id, external_id and the network's entry
AuthenticateA long random secret in the URL pathX-EC-Signature, keyed with the account's secret
RetriesMeta's own, for up to 7 daysNone: one attempt
Copy keptNoneNone

Come indirizzi i messaggi di un numero verso il tuo endpoint?

Fornisci un URL HTTPS il cui percorso contenga un segreto lungo e casuale, più un token di verifica: webhook_verify_token in una sessione di connessione, da 8 a 200 caratteri, oppure verify_token nella PUT. Meta controlla subito l'URL con una GET che porta hub.mode=subscribe, hub.verify_token e hub.challenge, e il tuo endpoint deve rispondere con il valore di hub.challenge se il token corrisponde. Se questo handshake fallisce, la PUT restituisce 502 meta_rejected con il messaggio di Meta; in una sessione di connessione il numero si connette comunque, e last_error della sessione spiega perché l'URL non è stato applicato.

Node.js: Meta's handshake and the path secret
import express from "express";
import { timingSafeEqual } from "node:crypto";

const PATH_SECRET = process.env.WA_PATH_SECRET; // the random part of webhook_url
const VERIFY_TOKEN = process.env.WA_VERIFY_TOKEN; // the verify token you sent
const app = express();

function same(a, b) {
  const x = Buffer.from(String(a)), y = Buffer.from(String(b));
  return x.length === y.length && timingSafeEqual(x, y);
}

// Meta's handshake, run when the destination is set
app.get("/wa/:secret", (req, res) => {
  if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
  if (req.query["hub.mode"] !== "subscribe" || !same(req.query["hub.verify_token"], VERIFY_TOKEN)) {
    return res.sendStatus(403);
  }
  res.send(req.query["hub.challenge"]);
});

// Messages, echoes and the one-time import; payloads reach 3 MB
app.post("/wa/:secret", express.json({ limit: "4mb" }), (req, res) => {
  if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
  res.sendStatus(200); // answer first: Meta retries for up to 7 days
  enqueue(req.body); // deduplicate on each message id before acting
});

Perché non puoi verificare la firma di Meta, e cosa la sostituisce?

Meta firma ogni consegna con X-Hub-Signature-256, un HMAC-SHA256 del payload calcolato con l'App Secret dell'app ricevente. Per i numeri dei tuoi clienti quell'app è l'app Tech Provider di easyCoexistence, il cui segreto non viene mai condiviso, quindi l'header non può essere verificato dal tuo lato. La credenziale è il segreto lungo e casuale nel percorso dell'URL: confrontalo in tempo costante e rifiuta tutto il resto. Come secondo livello, inserisci in allowlist le rotte registrate a Meta come AS32934 e aggiornala, perché Meta cambia periodicamente i propri indirizzi IP.

Quali webhook WhatsApp raggiungono il tuo URL?

I campi che Meta consente a un URL di callback alternativo: messages, per ciò che inviano i clienti e lo stato di ciò che invii; smb_message_echoes, per ciò che l'azienda invia dall'app WhatsApp Business; e la cronologia dell'importazione una tantum e smb_app_state_sync. Meta non invia mai webhook di template, né webhook di account come account_update, a una destinazione sostitutiva. Arrivano invece al callback di easyCoexistence, motivo per cui la revisione dei template viene letta con il polling e uno scarto ti arriva come evento di stato.

  • La destinazione è impostata sul WhatsApp Business Account, quindi due numeri nello stesso account la condividono: instrada su value.metadata.phone_number_id.
  • I media arrivano come ID; scarica il file da Meta con il token del cliente dalla chiamata delle credenziali.
  • I payload possono raggiungere 3 MB, quindi alza ogni limite di dimensione del body impostato al di sotto di questo valore.

Come appare un evento social inoltrato?

Una POST con Content-Type application/json e un header X-EC-Signature, con quattro chiavi: platform; account_id, l'ID del canale che usa la Partner API; external_id, l'ID dell'account sulla rete; ed entry. Per Instagram e Facebook, entry è l'entry del webhook di Meta invariato, con changes per commenti e menzioni e messaging per i DM. Per TikTok contiene l'evento comment.update con il contenuto analizzato, e comment_id, video_id e parent_comment_id come stringhe, così gli ID a 64 bit non vengono arrotondati.

  • Gli account Instagram sono iscritti a commenti, messaggi e menzioni; le Pagine Facebook a feed, messaggi e menzioni; TikTok invia comment.update.
  • easyCoexistence non riceve eventi di commento da YouTube o LinkedIn: la loro PUT risponde 400 not_supported, e i loro commenti si leggono tramite l'API di ciascuna rete con le credenziali.
  • Gli inoltri non portano l'header X-EC-Event né X-EC-Delivery, quindi deduplica sugli ID propri della rete, come un ID di commento o un mid di messaggio.
A forwarded Instagram comment
{
  "platform": "instagram",
  "account_id": "<CHANNEL_ID>",
  "external_id": "<INSTAGRAM_ACCOUNT_ID>",
  "entry": {
    "id": "<INSTAGRAM_ACCOUNT_ID>",
    "time": 1793440800,
    "changes": [
      {
        "field": "comments",
        "value": {
          "id": "<COMMENT_ID>",
          "from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
          "text": "<COMMENT_TEXT>",
          "media": { "id": "<MEDIA_ID>", "media_product_type": "<MEDIA_PRODUCT_TYPE>" }
        }
      }
    ]
  }
}

Come verifichi X-EC-Signature, passo per passo?

Con il signing_secret restituito da PUT /channels/{id}/webhook, mostrato una sola volta e unico per quell'account. L'header è nella forma t=<unix>,v1=<hex>. Poi, per ogni consegna:

  • Leggi il body grezzo della richiesta come byte, prima di qualsiasi parsing JSON.
  • Dividi l'header per virgole in t, un tempo Unix in secondi, e v1, un digest esadecimale.
  • Rifiuta la consegna se t dista più di 5 minuti dal tuo orologio.
  • Calcola HMAC-SHA256 su t, un punto e il body grezzo, con il segreto di quell'account, in esadecimale.
  • Confronta il risultato con v1 in tempo costante, poi rispondi con 2xx e metti il lavoro in coda.
Node.js: verifying a forwarded event
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();
const secrets = new Map(); // channel id -> signing_secret, kept in your database

app.post("/hooks/social", express.raw({ type: "application/json" }), (req, res) => {
  const sig = Object.fromEntries(
    (req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("=", 2)),
  );
  if (!/^\d+$/.test(sig.t ?? "") || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) {
    return res.sendStatus(401); // missing or stale timestamp
  }
  let event;
  try {
    event = JSON.parse(req.body.toString("utf8")); // platform, account_id, external_id, entry
  } catch {
    return res.sendStatus(400);
  }
  const secret = secrets.get(event.account_id);
  if (!secret || !sig.v1) return res.sendStatus(401);
  const expected = createHmac("sha256", secret)
    .update(sig.t + ".")
    .update(req.body) // the raw bytes, exactly as they arrived
    .digest("hex");
  if (expected.length !== sig.v1.length ||
      !timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1))) {
    return res.sendStatus(401);
  }
  res.sendStatus(204); // one attempt and no retries: acknowledge, then work
  enqueue(event);
});

Cosa succede quando non è impostata alcuna destinazione?

Non ti arriva nulla, e nulla attende di essere inviato più tardi. Un numero senza webhook_url ricade sul callback di easyCoexistence, dove i suoi messaggi vengono scartati senza essere memorizzati, e non riceve l'importazione della cronologia delle chat, che viene richiesta solo quando esiste una destinazione. Un account social senza destinazione non viene inoltrato: i suoi eventi raggiungono comunque l'app di easyCoexistence, ma nessuno viene conservato per te. Imposta ogni destinazione prima di aver bisogno del traffico.

Cosa succede a una destinazione quando una connessione cade o viene rimossa?

Un numero mantiene la propria destinazione registrata. Quando un numero caduto si riconnette, easyCoexistence reimposta di nuovo il tuo URL presso Meta, e lo stesso accade quando un numero sospeso torna attivo. Rimuovere un account social cancella la sua destinazione e il suo segreto, quindi dopo la riconnessione chiama di nuovo PUT /channels/{id}/webhook e salva il nuovo segreto. Quella PUT emette un nuovo segreto ogni volta che viene chiamata con un URL, e il vecchio smette subito di firmare.

Come configurarlo

  1. Put a secret in the URLChoose an HTTPS URL whose path holds a long random string, 200 characters or fewer in all, and make its GET answer Meta's hub.challenge.
  2. Route the number's messagesSend webhook_url and webhook_verify_token on the connect session, or PUT /connections/{id}/webhook once the number is connected.
  3. Turn on each social accountCall PUT /channels/{id}/webhook with your URL and store the signing_secret it returns against that channel.
  4. Verify, then acknowledgeCheck the path secret on WhatsApp deliveries and X-EC-Signature on forwarded ones, answer 2xx at once, then process from a queue.

Errori comuni

  • Controllare X-Hub-Signature-256 sulle consegne WhatsApp dei tuoi clienti. Meta lo calcola con il segreto dell'app di easyCoexistence, che non viene mai condiviso, quindi il controllo non può superarsi: autentica con il segreto nel percorso dell'URL.
  • Verificare X-EC-Signature sul JSON già analizzato. L'HMAC copre il body grezzo byte per byte, e riserializzarlo cambia i byte, quindi verifica prima del parsing.
  • Usare un solo segreto per ogni canale. Ogni account social firma con il proprio segreto, e gli eventi di stato con un altro, quindi cerca il segreto tramite account_id.
  • Fare lavoro lento prima di rispondere a un evento inoltrato. Viene inviato una sola volta, attende 8 secondi la tua risposta e non viene mai riprovato, quindi rispondi prima con 2xx, ed elabora dopo.
Farlo con EasyCoexistence

easyCoexistence instrada i messaggi di ogni numero dei tuoi clienti da Meta direttamente al tuo server e inoltra al tuo endpoint, appena arrivano, i commenti e i DM di Instagram e Facebook e i commenti di TikTok, firmati per account, senza copia conservata e con ogni connessione monitorata 24/7. Da US$ 9 a US$ 0,75 per connessione al mese, con il prezzo che scende man mano che aggiungi connessioni, e con i primi 3 giorni di prova gratuita.

Domande frequenti

Posso verificare la firma di Meta sui messaggi WhatsApp dei miei clienti?

No. Meta li firma con il segreto dell'app Tech Provider di easyCoexistence, che non viene mai condiviso. Autentica con il segreto lungo e casuale nel percorso del tuo URL e, facoltativamente, con gli intervalli IP di Meta.

Le connessioni YouTube e LinkedIn inoltrano eventi di commento?

No. easyCoexistence non riceve eventi di commento da nessuna delle due, quindi PUT /channels/{id}/webhook risponde 400 not_supported. Leggi i loro commenti tramite l'API di ciascuna rete con le credenziali del canale.

Gli eventi social inoltrati vengono riprovati se il mio server è spento?

No. Ciascuno viene inviato una sola volta e non viene conservata alcuna copia. Le consegne WhatsApp sono diverse, perché Meta stessa le riprova per fino a 7 giorni.

I messaggi passano da easyCoexistence?

Non su WhatsApp: Meta consegna i messaggi di un numero direttamente al webhook che imposti. Commenti e DM dai social network vengono inoltrati al tuo endpoint appena arrivano, firmati per account, senza copia conservata.

Continua a leggere

Collega il tuo primo canale in due minuti.

Nessuna revisione delle piattaforme da aspettare. Collega WhatsApp, Instagram, TikTok o un altro canale, poi chiedi alla tua AI di pubblicare, rispondere o fare un report, e guardala al lavoro.

  • 3 giorni gratis
  • Disdici quando vuoi
  • Solo API ufficiali
  • Monitorato 24/7

Verificato il