How sucaslilva/integracaohubspot works
Project Type and Purpose
• This is a backend-only REST API built with Spring Boot (Java/Maven).
• Its sole purpose is to integrate with HubSpot CRM: perform OAuth2 authentication, create/list contacts, and receive HubSpot webhooks.
File Structure
• Top-level folders:
• hubSpot/ (Maven project root)
• src/main/java/br/com/sucaslilva/hubSpot/{controller, service, model}
• src/main/resources/application.properties
• src/test/java/… (unit tests)
• Pattern: a classic 3-layered architecture (Controller → Service → External API), no internal database or persistence layer.
• Configuration: application.properties holds environment-injected OAuth client ID/secret, redirect URIs, etc.
Core Components
a. Clients (Postman, Web or Mobile Front-end)
b. Spring Boot REST API (hubSpot application)
• Controllers:
• AutenticacaoController (OAuth2 handshake)
• ContatoController (create/list contacts)
• WebhookController (receive HubSpot webhook callbacks)
• Services:
• TokenService (manage OAuth tokens)
• ContatoService (map API calls to HubSpot contacts endpoints)
• WebhookService (process incoming webhook events)
• Configuration Module (application.properties + environment variables)
c. External Service: HubSpot CRM REST API
d. Optional: Developer Tools (Postman collection for testing)
Relationships and Data Flows
• OAuth2 Flow
1. Client calls AutenticacaoController → forwards user to HubSpot’s auth endpoint
2. HubSpot redirects back with auth code → AutenticacaoController exchanges code via TokenService → stores access/refresh tokens in memory (or cache).
• Contact Management
1. Client calls ContatoController (create/list) → ContatoService adds Authorization header with access token → calls HubSpot Contacts API → returns contact data back to client.
• Webhook Handling
1. HubSpot sends HTTP POST to WebhookController endpoint → WebhookService validates signature and processes the JSON payload → triggers any business logic (e.g., logging or notifying another system).
Architectural Patterns and Principles
• Layered (MVC-inspired): Controllers orchestrate request/response; Services handle business logic/integration.
• External Integration: All persistent data lives in HubSpot; this API acts as a stateless proxy/adapter.
• Configuration-Driven: OAuth credentials and endpoints are injected via application.properties and environment variables.
• Statelessness: Each HTTP request is self-contained with its own authentication token.
Technologies and Frameworks to Annotate
• Java 17, Spring Boot (Web, Security/OAuth2)
• Maven (pom.xml)
• HubSpot REST API (OAuth2, Contacts endpoints, Webhooks)
• Postman (testing/collection)