Documentação de integração
Conecte outros softwares ao NeuroHub Meta para incorporar o onboarding de canais e receber eventos autenticados de WhatsApp Business, Messenger e Instagram.
O contrato público, sem ambiguidades
O hub é a camada de onboarding e roteamento de eventos oficiais da Meta. Ele mantém credenciais e tokens no servidor, entregando ao software parceiro apenas o que é necessário para operar a integração.
Suportado
- Receber eventos Meta por forwarding HTTPS.
- Abrir onboarding de WABA, Messenger e Instagram.
- Consultar a disponibilidade do serviço.
- Filtrar destinos por produto/canal.
Fora deste contrato
- O hub não expõe tokens de canal para terceiros.
- O hub não envia mensagens como proxy da Graph API.
- Apps e canais não possuem listagem pública.
- A sessão do painel não é credencial de integração.
Do endpoint ao primeiro evento
Disponibilize uma URL HTTPS que aceite POST JSON, por exemplo https://seu-software.com/webhooks/neurohub.
No painel, abra Apps → Editar → Outros pontos, informe a URL, selecione o produto e gere um segredo dedicado. O gerador usa 256 bits de entropia e entrega 64 caracteres hexadecimais.
Leia os bytes originais antes do parse JSON. Eles são necessários para validar a assinatura HMAC.
Confirme o recebimento após persistir ou enfileirar o evento. Processamento pesado deve ocorrer de forma assíncrona no seu software.
Envie uma mensagem ao canal conectado e confirme o status do forwarding no painel do hub.
Contrato de entrega de eventos
O destino recebe o mesmo corpo JSON autenticado que chegou da Meta. O hub não remodela nem remove campos do payload.
- Método
POST- Content-Type
application/json- X-Hub-App
- Identificador interno do app que recebeu o evento.
- X-NeuroHub-Timestamp
- Unix timestamp, em segundos, incluído no material assinado para proteção contra replay.
- X-NeuroHub-Signature-256
- HMAC próprio do hub no formato
sha256=<hex>, calculado com o segredo dedicado do destino. - X-Hub-Signature-256
- Assinatura original da Meta, preservada apenas como proveniência. Não exige nem justifica compartilhar o App Secret.
- Corpo
- Envelope original da Meta; a estrutura varia por produto e tipo de evento.
- Sucesso
- Qualquer resposta HTTP entre
200e299.
{
"object": "whatsapp_business_account",
"entry": [{
"id": "WABA_ID",
"changes": [{
"field": "messages",
"value": {
"metadata": { "phone_number_id": "PHONE_NUMBER_ID" },
"messages": [{
"id": "wamid.EXEMPLO",
"from": "5511999999999",
"type": "text",
"text": { "body": "Olá" }
}]
}
}]
}]
}Verifique antes de processar
Valide X-NeuroHub-Signature-256 com o segredo dedicado do destino. O material assinado é timestamp + "." + corpo bruto. Rejeite timestamps fora de uma janela curta e compare o HMAC em tempo constante.
import { createHmac, timingSafeEqual } from "node:crypto";
function validSignature(rawBody, timestamp, received, partnerSecret) {
if (!/^\d{10}$/.test(timestamp)) return false;
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
const expected = "sha256=" + createHmac("sha256", partnerSecret)
.update(timestamp + ".")
.update(rawBody)
.digest("hex");
const a = Buffer.from(received || "");
const b = Buffer.from(expected);
return a.length === b.length && timingSafeEqual(a, b);
}JSON.parse antes de validar e nunca compartilhe o App Secret da Meta. Compartilhe somente o segredo dedicado do destino, por canal seguro, e rotacione-o informando um novo valor no editor.Conexão incorporável de canais
Ative Permitir botão público de conexão no app e copie o snippet gerado no próprio card. O hub cria um state assinado e conduz o usuário pelo fluxo oficial da Meta.
GET /embed/connect?app=APP_PUBLICADO&channel=waba&lang=pt| Parâmetro | Obrigatório | Valores | Uso |
|---|---|---|---|
app | Sim | Gerado pelo hub | Use exatamente o valor presente no snippet do painel. |
channel | Sim | waba, messenger, instagram | Seleciona o fluxo de conexão. |
lang | Não | pt, en, es | Idioma da interface; padrão pt. |
Saúde do serviço
GET /health
{
"status": "ok",
"uptime": 3600.25,
"apps": 1,
"channels": 3
}Considere o hub disponível quando a resposta for 200 e status for ok. Os contadores são informativos e não substituem uma API de inventário.
Comportamento operacional
Cada evento gera uma tentativa por destino. Não há retry automático; use alertas e reconciliação no parceiro.
O padrão operacional é 10 segundos. Responda após enfileirar, não após concluir tarefas pesadas.
O hub não segue 3xx. Configure diretamente a URL HTTPS final.
Formato e IPs literais são validados ao salvar; DNS privado/reservado é bloqueado novamente antes de cada envio.
A assinatura NeuroHub é calculada sobre o timestamp e os mesmos bytes de payload aceitos da Meta.
Qualquer outro status é registrado como falha no histórico, quando o histórico estiver ativo.
Solução de problemas
O destino foi recusado ao salvar
Use HTTPS, sem credenciais na URL, sem fragmento e sem host local ou IP literal privado/reservado. Para domínios, a resolução DNS é validada e fixada imediatamente antes de cada entrega.
O evento não chegou ao meu software
Confirme que o destino está ativo, que o filtro inclui o produto correto e que a Meta enviou um webhook assinado ao app. Consulte o status do forwarding no histórico do painel.
O onboarding mostra “indisponível”
O app pode estar sem embed público, sem credenciais completas ou com um canal inválido. Gere novamente o snippet no card do app após salvar a configuração.
Posso listar canais ou enviar mensagens por essa API?
Não neste contrato público. O hub mantém tokens e inventário protegidos e não funciona como proxy de envio. Para uma integração parceira com API própria e credenciais dedicadas, fale com a @goldneuron.io.