Verificar um endpoint webhook do WhatsApp
Antes de entregar qualquer evento, a Meta chama o seu endpoint com um GET que inclui hub.mode, hub.verify_token e hub.challenge. O seu endpoint tem de comparar o token e devolver o desafio como corpo bruto. Qualquer outra resposta impede o início da entrega.
O valor que tem de ser devolvido no corpo da resposta.
O valor de hub.mode num pedido de verificação.
O único esquema que a Meta verifica. HTTP é rejeitado antes da chamada.
O que envia exatamente a Meta?
Um pedido GET para o seu URL com três parâmetros de consulta. hub.mode fica definido como subscribe. hub.verify_token é o token que configurou ao definir o destino. hub.challenge é um valor que a Meta gera para esta tentativa.
O seu endpoint deve comparar hub.verify_token com o token que escolheu e, se coincidirem, responder 200 com hub.challenge como corpo integral da resposta. Não o envolva em JSON, não coloque aspas à volta e não acrescente uma nova linha no fim, como algumas frameworks fazem por predefinição.
Se os tokens não coincidirem, responda 403. Esse é todo o protocolo, deliberadamente simples.
Por que falha silenciosamente uma resposta errada?
Porque uma falha na verificação não é um erro no seu sistema, mas uma ausência no sistema da Meta.
Quando o desafio não é devolvido corretamente, a Meta simplesmente não começa a entregar eventos nesse destino. O seu servidor responde 200 à verificação, os registos mostram que chegou um pedido e nenhum painel assinala um problema. O único sintoma é a ausência de mensagens, que a maioria das pessoas diagnostica como um problema de Coexistence, e não como um problema de handshake.
É por isso que vale a pena validar antes da chamada. Verificamos se o URL usa HTTPS e se foi fornecido um token de verificação antes de fazer o pedido Graph, para que um destino malformado falhe de imediato, em vez de parecer ligado.
O que mais pode impedir a verificação?
Três coisas que não têm nada que ver com o código.
Autenticação à frente do endpoint. Um gateway, uma camada de autenticação básica ou uma lista de permissões de IP rejeitará o pedido da Meta, que não tem credenciais para apresentar. A rota de verificação tem de estar acessível sem elas.
Um redirecionamento. A Meta chama o URL que lhe forneceu, e um 301 para um anfitrião canónico não é seguido de forma a concluir o handshake. Forneça-lhe o URL final.
E uma framework que serializa a resposta. Devolver uma cadeia de texto a partir de um handler que envolve tudo em JSON produz um corpo com aspas à volta do desafio, que não corresponde.
Erros comuns
- Devolver JSON. O corpo tem de ser apenas o valor bruto do desafio.
- Colocar o endpoint atrás de autenticação. A Meta não tem credenciais e o pedido será rejeitado.
- Fornecer à Meta um URL que redireciona. Use o URL final.
A EasyCoexistence valida se um destino usa HTTPS e tem um token de verificação antes de chamar a Meta, e regista uma verificação falhada na cronologia da ligação, em vez de descartar o destino.
Perguntas frequentes
Que token devo usar?
Qualquer cadeia de texto que escolha. Serve para o seu endpoint distinguir o pedido da Meta de qualquer outro pedido de alguém que descubra o URL.
Com que frequência ocorre a verificação?
Durante a configuração e novamente sempre que o destino é definido. Um endpoint funcional não é verificado de novo em cada evento.
Posso testá-lo sozinho?
Sim. Chame o seu próprio endpoint com os três parâmetros e confirme que o corpo regressa exatamente com o valor do desafio.
E se o meu servidor estivesse indisponível durante a verificação?
O handshake falha e o destino não é ativado. Guardá-lo novamente executa a verificação outra vez.
Continue a ler
Pronto para começar?
Configure a Coexistência do WhatsApp em minutos, não em meses. A aplicação continua a funcionar no telemóvel.
Começar período experimental gratuitoVerificado em