Verificando um endpoint de webhook do WhatsApp
Antes de entregar qualquer evento, a Meta chama o seu endpoint com um GET que leva hub.mode, hub.verify_token e hub.challenge. O seu endpoint precisa comparar o token e devolver o challenge como corpo puro da resposta. Qualquer outra coisa e a entrega nunca começa.
O valor que precisa ser devolvido como corpo da resposta.
O valor de hub.mode em uma requisição de verificação.
O único esquema que a Meta verifica. HTTP é recusado antes da chamada.
O que exatamente a Meta envia?
Uma requisição GET para a sua URL com três parâmetros de query. hub.mode vem com o valor subscribe. hub.verify_token é o token que você configurou ao definir o destino. hub.challenge é um valor que a Meta gera para essa tentativa.
O seu endpoint deve comparar hub.verify_token com o token que você escolheu e, se combinar, responder 200 com hub.challenge como todo o corpo da resposta. Sem embrulhar em JSON, sem aspas em volta, sem a quebra de linha no final que alguns frameworks acrescentam por padrão.
Se o token não combinar, responda 403. Esse é o protocolo inteiro, e ele é pequeno de propósito.
Por que uma resposta errada falha em silêncio?
Porque a verificação falhar não é um erro no seu sistema, é uma ausência no da Meta.
Quando o challenge não é devolvido corretamente, a Meta simplesmente não começa a entregar naquele destino. O seu servidor devolve 200 para a verificação, os seus logs mostram que uma requisição chegou, e nenhum painel em lugar nenhum relata problema. O único sintoma é que as mensagens nunca chegam, o que a maioria das pessoas diagnostica como problema de Coexistência em vez de problema de handshake.
É por isso que validar antes da chamada vale a pena. Nós checamos que a URL é HTTPS e que um verify token foi informado antes de fazer a requisição no Graph, então um destino malformado falha na hora em vez de parecer conectado.
O que mais pode bloquear a verificação?
Três coisas que não têm nada a ver com o código.
Autenticação na frente do endpoint. Um gateway, uma camada de basic auth ou uma lista de IPs permitidos vai recusar a requisição da Meta, e a Meta não tem credencial nenhuma para apresentar. A rota de verificação precisa estar acessível sem isso.
Um redirecionamento. A Meta chama a URL que você deu, e um 301 para um host canônico não é seguido de um jeito que complete o handshake. Entregue a URL final.
E um framework que serializa a resposta. Devolver uma string de um handler que embrulha tudo em JSON produz um corpo com aspas em volta do challenge, e isso não combina.
Erros comuns
- Devolver JSON. O corpo precisa ser o valor puro do challenge, sem nada em volta.
- Colocar o endpoint atrás de autenticação. A Meta não tem credenciais e vai ser recusada.
- Dar à Meta uma URL que redireciona. Use a final.
A EasyCoexistence valida que um destino é HTTPS e tem verify token antes de chamar a Meta, e registra um handshake falho na linha do tempo da conexão em vez de descartar o destino.
Perguntas frequentes
Que token eu devo usar?
Qualquer texto que você escolher. Ele existe para o seu endpoint distinguir a requisição da Meta da de qualquer um que descubra a URL.
Com que frequência a verificação acontece?
Na configuração, e de novo sempre que o destino é definido. Um endpoint que funciona não é reverificado em cada evento.
Posso testar por conta própria?
Sim. Chame o seu próprio endpoint com os três parâmetros e confira que o corpo volta exatamente como o valor do challenge.
E se o meu servidor estava fora durante a verificação?
O handshake falha e o destino não é ativado. Salvar de novo faz a verificação rodar outra vez.
Continue lendo
Pronto para começar?
Configure o WhatsApp Coexistence em minutos, não em meses. O aplicativo continua funcionando no celular.
Começar teste grátisVerificado em