Segurança
Segredos devem permanecer no backend. O frontend do cliente final nunca precisa conhecer a Partner API Key ou o token Meta.
Classificação de credenciais
| Credencial | Onde usar | Pode ir ao frontend? |
|---|---|---|
| Publishable Key | Header apikey | Sim, mas prefira configuração central |
| Partner API Key | Backend do SaaS partner | Não |
| Meta Access Token | Backend para Graph API | Não |
| Meta Verify Token | Endpoint de webhook | Não exibir ao cliente final |
| Webhook signing secret | Validação HMAC HookCloud | Não |
| INTERNAL_EDGE_SECRET | Crons internos HookCloud | Nunca fora da infraestrutura |
Armazenamento
- Use secret manager ou variáveis de ambiente
- Criptografe tokens em repouso
- Não registre headers Authorization
- Masque segredos em ferramentas de observabilidade
- Rotacione após suspeita de exposição
- Separe test e live
Webhook seguro
- HTTPS obrigatório.
- Valide o challenge GET.
- Verifique HMAC dos eventos HookCloud.
- Use comparação em tempo constante.
- Valide timestamp com tolerância curta.
- Deduplicate por ID.
- Responda 2xx antes de processamento pesado.
- Bloqueie redirects e destinos privados em qualquer callback configurável.
Autorização e escopo
Use a Partner API Key somente para recursos do próprio partner. Se enviar partner_id explicitamente com o ID de outro parceiro, a API retorna 403 partner_scope_mismatch; o parâmetro não troca o parceiro autenticado. No seu SaaS, aplique autorização por cliente antes de expor status, templates ou ações de instância.
Privacidade operacional
A HookCloud não precisa receber conteúdo das mensagens para oferecer saúde de entregas. Reporte somente IDs técnicos, status, códigos de erro e hashes. O BSUID pode ser enviado nos campos documentados de identificação; a HookCloud o converte em hash para o registro de saúde.
Política de privacidade: partner-politica-de-privacidade.hookcloud.app.
Checklist de go-live
- Partner API Key apenas no backend
- Meta token criptografado
- Webhook responde GET e POST
- HMAC validado
- Fila e retries configurados
- Logs sem PII desnecessária
- Timeouts e limites de payload
- Monitoramento de 4xx/5xx
- Backup e recuperação testados
- Política e termos publicados
Escopos explícitos por credencial
Uma Partner API Key com lista vazia de escopos não tem acesso às rotas. Use os escopos necessários por serviço: instances.read para consulta, instances.credentials.read para revelar o token Meta e webhook.read para consultar a configuração do callback. O curinga * é uma concessão explícita de acesso amplo, não o padrão inferido de uma lista vazia.
Use HTTPS e combine a chave pública e a chave do parceiro do mesmo ambiente. Chaves com escopo de leitura não podem atualizar endpoint nem dados de cliente.