WhatsApp Entrypoint
O whatsapp-entrypoint é a porta de entrada e saída de dados entre a plataforma EcomSmart e a Meta Cloud API. Ele atua como um túnel puro: valida webhooks, descriptografa payloads de WhatsApp Flows, roteia mensagens para os agentes downstream e expõe endpoints padronizados para envio de mensagens ativas.
O serviço opera de forma totalmente agnóstica a regras de negócio: não manipula carrinhos nem mantém FSMs, limitando-se a traduzir o protocolo da Meta e distribuí-lo com segurança na rede interna.
Papel na Plataforma
flowchart LR
meta[Meta Cloud API] -->|Webhook público| wpp[WhatsApp Entrypoint]
wpp -->|Dedup & Roteamento| redis[(Redis)]
wpp -->|POST /api/v1/events/| b2c[Agente B2C]
wpp -->|POST /api/v1/events/| b2b[Agente B2B]
wpp <-->|POST /api/v1/flow-exchange/| b2c
wpp <-->|POST /api/v1/flow-exchange/| b2b
b2c -->|POST /send-*| wpp
b2b -->|POST /send-*| wpp
wpp -->|Graph API / HTTPS| meta
style meta fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
style wpp fill:#f0f9ff,stroke:#0284c7,stroke-width:2px,color:#0369a1
style redis fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e
style b2c fill:#f0fdf4,stroke:#16a34a,stroke-width:1.5px,color:#166534
style b2b fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#6b21a8
Limites de Responsabilidade
| É responsabilidade do Entrypoint | NÃO é responsabilidade do Entrypoint |
|---|---|
Validar assinaturas HMAC-SHA256 (x-hub-signature-256) em todas as entradas. |
Processar FSM de conversa ou intenção semântica do cliente. |
| Deduplicação de eventos de mensagens repetidas pela Meta via Redis. | Persistir dados de pedidos, catálogos ou clientes. |
| Criptografia RSA-OAEP e AES-GCM bidirecional para WhatsApp Flows. | Decidir regras de frete, pagamento ou checkout. |
Roteamento multi-tenant por phone_number_id (loja B2C vs número central B2B). |
Gerar cópias de copywriting ou prompts de IA. |
| Envio de mensagens unificadas (texto, botões, listas, templates, Flows). | Armazenar histórico definitivo de pedidos. |
| Gerenciamento de ciclo de vida de Flows e templates na Meta Graph API. |
Fluxo de Ingress e Deduplicação
A Meta exige confirmação HTTP rápida (tempo limite padrão de 15 segundos). Para evitar timeouts e processamento duplicado, o serviço processa em duas fases:
sequenceDiagram
autonumber
actor Meta as Meta Cloud API
participant EP as WhatsApp Entrypoint
participant Redis as Redis (Dedup)
participant Downstream as Agente (B2C / B2B)
Meta->>EP: POST /api/v1/webhook/ (HMAC assinado)
EP->>EP: Valida X-Hub-Signature-256
EP->>Redis: SET NX whatsapp:msg:{id} (TTL 24h)
alt Chave já existia no Redis
EP-->>Meta: 200 OK (Descarte idempotente)
else Chave nova registrada
EP-->>Meta: 200 OK (Confirmação imediata)
EP-)Downstream: BackgroundTask: POST /api/v1/events/
end
- Assinatura HMAC: Rejeita requisições forjadas ou sem assinatura correspondente ao
META_APP_SECRET. - Deduplicação Atômica:
SET whatsapp:msg:{id} 1 NX EX 86400no Redis. Se a chave já existir (retry da Meta), o evento é descartado com200 OK. - Resolução de Tenant: Identifica se o
phone_number_idpertence a um lojista cadastrado (encaminha para o Agente B2C) ou ao número central da plataforma (encaminha para o Agente B2B). - Despacho em Background: O handshake HTTP com a Meta fecha em
< 50ms; o processamento pesado ocorre viaBackgroundTasks.
Criptografia de WhatsApp Flows
Os WhatsApp Flows exigem cifragem ponta a ponta entre a Meta e o backend pelo endpoint /api/v1/webhook/flow/:
flowchart TD
req[Payload Cifrado da Meta] --> rsa[Descriptografa chave AES com RSA Privada]
rsa --> aes[Descriptografa payload JSON com AES-GCM]
aes --> dispatch[POST /api/v1/flow-exchange/ para B2C ou B2B]
dispatch --> resp[Recebe tela/dados da próxima etapa]
resp --> cifrar[Cifra resposta com AES-GCM + IV novo]
cifrar --> ret[Retorna payload criptografado para a Meta]
style req fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
style rsa fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e
style aes fill:#f0f9ff,stroke:#0284c7,stroke-width:1.5px,color:#0369a1
style dispatch fill:#f0fdf4,stroke:#16a34a,stroke-width:1.5px,color:#166534
style cifrar fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#6b21a8
style ret fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
Contratos de API
Webhooks da Meta
| Método | Rota | Finalidade | Autenticação |
|---|---|---|---|
GET |
/api/v1/webhook/ |
Handshake de verificação do tenant central. | hub.verify_token |
GET |
/api/v1/webhook/{tenant_id}/ |
Handshake de verificação por lojista específico. | hub.verify_token |
POST |
/api/v1/webhook/ |
Recebe mensagens, status de entrega e carrinhos. | X-Hub-Signature-256 |
POST |
/api/v1/webhook/flow/ |
Data Endpoint interativo de WhatsApp Flows. | Criptografia RSA/AES |
Envio de Mensagens (Consumidores Internos)
Todos os endpoints de envio exigem o cabeçalho X-Internal-Key com o valor de WPP_API_KEY:
| Método | Rota | Descrição do Payload |
|---|---|---|
POST |
/api/v1/send-messages/send-text |
Texto simples com número de destino e token do WhatsApp. |
POST |
/api/v1/send-messages/send-buttons |
Mensagem interativa com até 3 botões de ação rápida. |
POST |
/api/v1/send-messages/send-list |
Lista interativa estruturada em seções e linhas selecionáveis. |
POST |
/api/v1/send-messages/send-flow |
Disparo de WhatsApp Flow nativo (ex: endereço B2C ou catálogo B2B). |
POST |
/api/v1/send-messages/send-template |
Disparo de template HSM aprovado pela Meta. |
POST |
/api/v1/send-messages/send-cta-url |
Botão interativo de redirecionamento para link externo de checkout. |
POST |
/api/v1/send-messages/send-product-list |
Carrossel de catálogo nativo com produtos e variações. |
Registry & Provisionamento
| Método | Rota | Uso |
|---|---|---|
POST |
/api/v1/registry/flows/create |
Pipeline completo de criação, upload de JSON e publicação de Flow. |
POST |
/api/v1/registry/templates/create |
Submissão de novos templates para aprovação na Graph API. |
POST |
/api/v1/onboarding/embedded-signup |
Conexão de WABA e número do lojista via Embedded Signup. |
Configuração Essencial
| Variável | Descrição | Crítica |
|---|---|---|
WPP_API_KEY |
Chave de proteção das rotas internas de envio de mensagens. | Sim |
META_APP_SECRET |
Segredo do aplicativo Meta para validar assinaturas HMAC. | Sim |
META_VERIFY_TOKEN |
Token do handshake de verificação de webhooks. | Sim |
META_FLOW_PRIVATE_KEY |
Chave privada RSA (PEM) usada para abrir interações de Flows. | Sim |
META_FLOW_PRIVATE_KEY_PASSPHRASE |
Senha da chave privada RSA (se aplicável). | Opcional |
REDIS_URL |
Conexão para deduplicação atômica e cache temporário. | Sim |
PLATFORM_API_URL |
URL do serviço de dados para resolver lojistas por phone_number_id. |
Sim |
B2C_URL |
Endereço interno do container do Agente B2C. | Sim |
B2B_URL |
Endereço interno do container do Agente B2B. | Sim |
Diagnóstico Rápido
- A Meta acusa erro de webhook: Verifique se o
META_APP_SECRETconfere exatamente com o painel de desenvolvedores da Meta. Assinaturas inválidas geram logHMAC signature verification failede resposta401. - Mensagens duplicadas sendo processadas: Inspecione a conectividade com o Redis. Se o Redis estiver indisponível, o serviço falha em modo aberto (processa sem dedup) para não perder vendas, gerando log de alerta.
- Falhas de tela em WhatsApp Flows: Verifique se a chave pública registrada na Meta corresponde à chave privada configurada em
META_FLOW_PRIVATE_KEY. Erros de descriptografia quebram o Flow imediatamente no cliente. - Mensagens downstream não entregues: Verifique se o
phone_number_idrecebido no webhook existe noplatform_api. Números não mapeados são registrados comoInbound webhook for unknown phone_number_ide ignorados.