Skip to content

Webhook por público

1. Introdução

Nesta opção, o WhatsApp (e qualquer outro provedor que dispare webhook público) não chama a API principal do PASI.

Em vez disso, existe um Webhook Service mínimo, dedicado e público, que faz somente o que precisa ser feito na borda: - valida origem e assinatura - valida formato/payload - aplica rate limit agressivo e proteções antifraude - controla idempotência (para evitar duplicar ações) - transforma o evento externo em um comando interno normalizado - chama o core interno usando uma service account (token interno)

O objetivo é parar de “afrouxar” a segurança do sistema inteiro por causa de uma integração pública (como aconteceu com AllowAnonymous espalhado).

2. Visão estratégica

2.1. O que esta opção resolve

  • Reduz drasticamente a superfície pública crítica: a API principal deixa de ser impactada por exigências de webhook público.
  • Isolamento de risco: qualquer abuso, ataque, varredura ou erro vindo do WhatsApp fica contido em um serviço pequeno e controlado.
  • Padroniza entrada externa: o webhook service vira o lugar certo para regras de borda (assinatura, origem, idempotência, rate limit).
  • Acelera “travar” o legado: dá para cortar rapidamente o AllowAnonymous do resto da API, mantendo apenas o webhook service público.

2.2. O que esta opção não resolve sozinha

  • O core ainda precisa de autorização real por vínculo: o webhook service não deve “virar regra de negócio”.
  • Idempotência precisa ser bem desenhada: sem isso, eventos repetidos podem gerar duplicidade (ex.: pagamento duplicado, criação duplicada, mudança de status em loop).
  • Observabilidade é obrigatória: para não virar caixa-preta, precisa de logs, correlação e trilha de auditoria do evento até a ação no core.

3. Visão de negócio

3.1. Benefícios

  • Menos risco e menos ruído operacional: reduz incidentes e comportamentos estranhos causados por exposição ampla da API.
  • Mais segurança para processos sensíveis: o WhatsApp deixa de ser justificativa para manter endpoints críticos abertos.
  • Antifraude e controle na borda: fica fácil aplicar limites agressivos e regras específicas sem afetar o restante dos consumidores.
  • Experiência mais previsível: eventos externos são normalizados antes de entrar no domínio, reduzindo inconsistência.

3.2. Pontos de atenção para o negócio

  • É preciso alinhar quais ações o WhatsApp pode disparar (escopo), e quais são proibidas.
  • É necessário definir claramente:
    • quais eventos existem,
    • o que cada evento significa,
    • quais validações e critérios de rejeição existem,
    • e como o sistema reage a reenvios e duplicidades (idempotência).

4. Fluxo de funcionamento

%%{init:{   "theme":"neutral",   "fontSize":22,   "flowchart":{"curve":"basis","htmlLabels":true,"nodeSpacing":50,"rankSpacing":70} }}%% flowchart TB   A["Origem externa envia webhook<br/>provedor parceiro chatbot"]:::ui_input --> B["Servico de Webhooks<br/>entrada publica minima"]:::ui_input   B --> C["Validacoes obrigatorias<br/>assinatura origem formato"]:::ui_input   C --> D{Webhook valido}:::decision   D -- Nao --> E["Rejeitar webhook<br/>retornar 400 ou 401"]:::ui_button   D -- Sim --> F["Controle de idempotencia<br/>evento unico"]:::ui_input   F --> G{Evento ja processado}:::decision   G -- Sim --> H["Ignorar evento repetido<br/>retornar 200"]:::ui_button   G -- Nao --> I["Gerar comando interno<br/>normalizar dados"]:::ui_input   I --> J["Obter token interno<br/>conta de servico"]:::ui_input   J --> K{Token interno valido}:::decision   K -- Nao --> L["Falha de seguranca<br/>bloquear e alertar"]:::ui_button   K -- Sim --> M["Chamar Core Interno<br/>operacao necessaria"]:::endpoint_post   M --> N["Core aplica regras de negocio<br/>e autorizacao por vinculo"]:::endpoint_post   N --> O["Registrar auditoria<br/>log e rastreabilidade"]:::ui_input   O --> P["Retornar resposta do webhook<br/>ack do processamento"]:::endpoint_get   classDef endpoint_get     fill:#e0f2fe,stroke:#0284c7,color:#0f172a,stroke-width:1px;   classDef endpoint_post    fill:#dcfce7,stroke:#16a34a,color:#052e16,stroke-width:1px;   classDef endpoint_put     fill:#fef9c3,stroke:#a16207,color:#3b2f0b,stroke-width:1px;   classDef endpoint_delete  fill:#fee2e2,stroke:#ef4444,color:#7f1d1d,stroke-width:1px;   classDef ui_input   fill:#eef2ff,stroke:#6366f1,color:#111827,stroke-width:1px;   classDef ui_button  fill:#ede9fe,stroke:#7c3aed,color:#1f2937,stroke-width:1px;   classDef decision   fill:#fff7ed,stroke:#f59e0b,color:#78350f,stroke-width:1px;

5. Manutenção e longo prazo

5.1. Manutenção do código

  • Serviço pequeno e bem definido: o webhook service tem um escopo limitado (bordas), então tende a ser estável e fácil de manter.
  • Risco reduzido de “arrastar legado”: o core pode evoluir sem depender de detalhes do provedor externo.
  • Exige disciplina no desenho: se começar a “colocar regra de negócio no webhook”, ele vira um mini-sistema e perde o objetivo.

Boas práticas para manter sustentável:

  • Contrato de eventos versionado (event type, schema, campos obrigatórios).
  • Idempotência persistida (chave do evento + status + timestamp).
  • Dead-letter e reprocessamento controlado (quando for necessário).
  • Observabilidade ponta a ponta (correlation id do webhook até a ação no core).

5.2. Escalabilidade

  • Escala separada da API principal: picos de webhook (ex.: WhatsApp) não derrubam o core por falta de controle.
  • Rate limit agressivo: como a borda é isolada, dá para bloquear rápido, limitar por IP/origem, impor janelas e thresholds.
  • Fila opcional: se volume crescer, o webhook service pode:
    • responder rápido com ACK,
    • enfileirar comando interno,
    • processar assíncrono com retry e DLQ.

(Importante: a fila melhora resiliência, mas aumenta complexidade; vale quando houver volume ou instabilidade real no provedor.)

6. Adaptação ao legado do PASI

No cenário atual do PASI, esta opção é quase sempre obrigatória, porque hoje o WhatsApp “puxa” a API para um modelo permissivo (muitos endpoints AllowAnonymous), o que cria risco sistêmico.

6.1. Caminho de adaptação recomendado

  1. Criar o Webhook Service e publicar como único ponto público
    • Deixar somente ele exposto para a internet para o caso WhatsApp.
  2. Migrar rotas do WhatsApp para ele
    • Tudo que hoje chama API principal de forma permissiva passa a entrar por esse serviço.
  3. Remover permissividade do resto da API
    • Revisar e eliminar AllowAnonymous do que não é webhook.
  4. Implementar idempotência real
    • Garantir que reenvio do provedor não duplica ações.
  5. Chamar core com service account
    • O core passa a aceitar apenas chamadas internas autenticadas e rastreáveis.
  6. Observabilidade e antifraude
    • Logs por evento, alertas de abuso, thresholds e bloqueios.

6.2. Por que esta opção é boa para transição

  • Ela reduz risco rápido sem exigir refatoração completa do core.
  • Ela cria uma camada de proteção e normalização que continua útil mesmo quando o core for reescrito.
  • Ela evita que integrações externas “contaminem” as regras de segurança dos portais e do superapp.

7. Principais prós e contras

7.1. Prós

  • Você para de manter a API inteira permissiva por causa do WhatsApp.
  • Reduz muito risco e ruído.
  • Fica mais fácil aplicar rate limit agressivo e antifraude.

7.2. Contras

  • É mais um componente para operar.
  • Exige desenho de eventos e idempotência (para não duplicar ações).

8. Quando esta opção faz sentido

  • Quase sempre quando existe webhook público.
  • Especialmente quando o legado foi “aberto demais” para suportar integração externa.
  • Quando você precisa de segurança forte e controle de abuso sem afetar os demais consumidores.