Verifica di un endpoint webhook WhatsApp

Cosa invia esattamente Meta?

Una richiesta GET al tuo URL con tre parametri di query. hub.mode è impostato su subscribe. hub.verify_token è il token che hai configurato quando hai impostato la destinazione. hub.challenge è un valore generato da Meta per questo tentativo.

Il tuo endpoint dovrebbe confrontare hub.verify_token con il token scelto e, se corrisponde, rispondere con 200 e hub.challenge come intero corpo della risposta. Non racchiuderlo in JSON, non aggiungere virgolette intorno e non inserire una nuova riga finale che alcuni framework aggiungono per impostazione predefinita.

Se il token non corrisponde, rispondi con 403. Questo è l'intero protocollo, volutamente essenziale.

Perché una risposta errata fallisce in silenzio?

Perché il fallimento della verifica non è un errore del tuo sistema, ma un'assenza nel sistema di Meta.

Quando la challenge non viene restituita correttamente, Meta semplicemente non inizia a consegnare dati a quella destinazione. Il tuo server restituisce 200 alla verifica, i log mostrano che è arrivata una richiesta e nessuna dashboard segnala un problema. L'unico sintomo è che i messaggi non arrivano mai, cosa che la maggior parte delle persone diagnostica come un problema di Coexistence anziché come un problema di handshake.

Per questo vale la pena validare tutto prima della chiamata. Verifichiamo che l'URL sia HTTPS e che sia stato fornito un token di verifica prima di effettuare la richiesta Graph, così una destinazione non valida fallisce subito invece di sembrare connessa.

Cos'altro può bloccare la verifica?

Tre cose che non hanno nulla a che vedere con il codice.

L'autenticazione davanti all'endpoint. Un gateway, un livello di autenticazione di base o un elenco di IP consentiti rifiuteranno la richiesta di Meta, che non ha credenziali da presentare. La route di verifica deve essere raggiungibile senza autenticazione.

Un reindirizzamento. Meta chiama l'URL che hai fornito e un 301 verso un host canonico non viene seguito in modo da completare l'handshake. Fornisci l'URL finale.

E un framework che serializza la risposta. Restituire una stringa da un gestore che racchiude tutto in JSON produce un corpo con virgolette intorno alla challenge, che quindi non corrisponde.

Errori comuni

• Restituire JSON. Il corpo deve contenere la challenge grezza, senza nient'altro intorno.
• Mettere l'endpoint dietro un'autenticazione. Meta non ha credenziali e la richiesta verrà rifiutata.
• Fornire a Meta un URL che reindirizza. Usa quello finale.

Domande frequenti

Continua a leggere