HubSpot Integration Project

Projeto que integra com a API do HubSpot, permitindo autenticação via OAuth 2.0 (authorization code flow), criação de contatos e recebimento de webhooks para contatos criados diretamente na plataforma.
🔗 Guia rápido OAuth no HubSpot

Tecnologias utilizadas

• Java 21 + Spring Boot
• HubSpot API
• OAuth 2.0
• Bucket4j (controle de limite de requisições conforme documentação do HubSpot)

---

Configuração Inicial no HubSpot

1. Crie uma conta de desenvolvedor: HubSpot Developer
2. Registre um novo aplicativo
3. Na aba Autenticação:
   • Adicione a URL de redirecionamento:
     http://localhost:8080/api/hubspot/oauth/callback
   • Copie o Client ID e o Client Secret para próxima etapa
   • Adicione os seguintes escopos obrigatórios mais abaixo na aba:
     • crm.objects.contacts.read
     • crm.objects.contacts.write
4. Na seção Webhooks, configure um webhook para callback de criação de contato pela plataforma:
   • O HubSpot apenas aceita url HTTPS para webhook, para testar o endpoint com HTTPS, utilize ferramentas como ngrok ou localtunnel apontado para a porta 8080
   • Adicione o link + o endpoint, ficando algo assim: open-ducks-pump.loca.lt/api/hubspot/webhook/contact-create
   • Objeto seria: Contato
   • Evento seria : Criado (contact.creation)
   • Ao concluir e listar o webhook, selecione e ative o funcionamento

Configuração do Projeto

No application.yml adicione suas credenciais:

hubspot-integration
    client-id=SEU_CLIENT_ID
hubspot.client-secret
    SEU_CLIENT_SECRET

Como rodar o projeto

Com o Maven instalado: ./mvnw spring-boot:run

Fluxo de Autenticação (OAuth) e Endpoints

1. Obter URL de autorização(acesse no navegador a url retornada)

GET http://localhost:8080/api/hubspot/oauth/authorize

2. Após autorizar, o HubSpot redireciona para a URL de callback com o code:

GET http://localhost:8080/api/hubspot/oauth/callback?code=XXXXX

O código é trocado por um token de acesso e salvo localmente.

3. Crie contato no HubSpot através do endpoint:

POST http://localhost:8080/api/hubspot/contacts

Exemplo de corpo da requisição:

{
  "firstname": "Maria",
  "lastname": "Silva",
  "email": "[email protected]"
}

O token salvo é usado para autenticar a criação no HubSpot. O contato também é armazenado localmente.

Webhook - Contato Criado via HubSpot

Após configurar o webhook no app HubSpot, sempre que um contato for criado pela plataforma, uma requisição será enviada para:

POST /api/hubspot/webhook/contact-create

• O sistema recebe o ID do novo contato
• Usa o token salvo para buscar os dados no HubSpot
• Salva localmente o contato com as informações atualizadas

Decisões tomadas

Regras

• A criação de contatos via POST com JSON permite maior flexibilidade de dados.
• O salvamento local (tanto ao criar quanto ao receber via webhook) simula um modelo B2B onde os dados precisam estar sincronizados entre sistemas.
• Não usei banco de dados pra ficar simples.
• Criei o "CRUD" de contato de forma mais genérica com estrutura de serviço preparada para expansão .

Tecnologias

• Bucket4j foi usado para respeitar limites de requisição da API do HubSpot.
• Spring Boot foi escolhido pela robustez e familiaridade.

Melhorias futuras

• Adicionar persistência em banco de dados
• Implementar cadastro dinâmico de apps/usuários (multi-tenant) para uso com vários aplicativos e integrações.
• Finalizar o CRUD completo de contatos (busca, atualização, exclusão)
• Expandir integração com outras entidades do HubSpot
• Adicionar chaves e testes de integração fim-a-fim (por exemplo com Cucumber ou Selenium) pra existir teste simulando todo o fluxo OAuth 2.0.