Segurança

Classificação de credenciais

Como obter sua chave da Partner API

O proprietário ou administrador acessa Portal → Integração → Sua chave da Partner API. A credencial inicial é disponibilizada após a confirmação da contratação, o cadastro obrigatório do responsável e a validação salva do webhook global. A chave permanece mascarada até clicar em Mostrar ou Copiar.

Se a preparação não for confirmada, use Conferir chave de API. A conferência preserva as credenciais existentes e não gera uma nova chave a cada atualização da página. Chaves revogadas, expiradas ou não recuperáveis não são reativadas ou substituídas automaticamente: solicite ao suporte a conferência e eventual substituição autorizada.

A Partner API Key autentica chamadas à HookCloud; o Meta Verify Token valida o desafio GET; a chave de assinatura do webhook verifica POSTs HookCloud. São segredos com finalidades diferentes. Não use o token GET como credencial da API.

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.

Política obrigatória de uso da API e consultas à Meta

1. Use os GETs locais da HookCloud para dados já sincronizados. Leia a origem e a data da evidência. Eles não consultam a Meta por item; não substituem uma verificação atual quando o caso exigir.
2. Mantenha cache separado por parceiro, cliente, WABA, número e geração da conexão. Invalide-o por eventos e mudanças de identidade; não reutilize dados de outro cliente. O prazo deve respeitar a finalidade e a validade do recurso. URLs temporárias de mídia não podem permanecer em cache depois de expirar.
3. Centralize consultas concorrentes equivalentes, aplique paginação e limites de concorrência. Não faça varreduras frequentes de todos os números ou templates. Evite refresh explícito em cada renderização.
4. Respeite os limites, sinais de uso e Retry-After quando informados. Em falhas transitórias, aplique backoff exponencial com dispersão e limite de tentativas. Erros de autenticação ou permissão exigem correção; não os repita em loop.
5. Guarde somente os dados necessários, proteja credenciais no servidor e não registre tokens nos logs. Webhooks precisam de validação de assinatura, deduplicação e tratamento de eventos fora de ordem.
6. A HookCloud poderá revisar a integração em caso de excesso recorrente, solicitar correções e avaliar medidas proporcionais conforme a evidência. Este aviso não significa suspensão automática por uma única consulta nem inventa uma penalidade da Meta.

O assinante deve orientar seus próprios clientes e implementar estas regras no sistema que controla. A franquia dos pacotes não elimina limites técnicos da Meta nem as regras de risco por cliente.

Referências: Limites de requisição Graph API · Webhooks oficiais.