External Integrations
Overview of all third-party service integrations in the Renewa One backend. Each integration has a dedicated client or service, with credentials managed in Infisical EU (project renewa-one).
Integration Map
| Service | Client Location | Purpose | Dedicated Page |
|---|---|---|---|
| HubSpot | backend/src/services/hubspot/ (33 files) | Bidirectional CRM sync | HubSpot Integration |
| sevDesk | backend/src/services/sevdesk/ | Accounting / invoice bridge | — |
| DocuSign | backend/src/lib/docusign-client.ts | E-signature in document flows | DocuSign |
| Azure Entra | backend/src/services/entra/ | SSO / identity provider, department + employee sync | Azure Entra |
| Dataverse | backend/src/lib/dataverse-client.ts | MS Dynamics data import | Dataverse |
| Resend | backend/src/lib/email/ | Transactional email | Resend Email |
| Bird (formerly MessageBird) | backend/src/lib/sms/ | SMS messaging | MessageBird SMS |
| Sentry | @sentry/bun, captured in middleware/errorHandler.ts | Error tracking | Sentry |
| S3 / Tigris | backend/src/lib/storage.ts (via FileService streams) | Object file storage (CAS) | Files |
| Upstash Redis | backend/src/lib/redis/ | Cache, BullMQ job queues, rate limiting | Background Jobs |
Credential Management
All external credentials live in Infisical EU — never in code, config files, or GitHub Environment Secrets (GitHub holds CI-infra credentials only). Synced envs get them via Infisical → Fly native sync; see Secret Management Operations.
| Secret | Service | Notes |
|---|---|---|
HUBSPOT_CLIENT_ID | HubSpot | Public OAuth app ID |
HUBSPOT_CLIENT_SECRET | HubSpot | Webhook signature validation (HMAC-SHA256 v3, 5-min window) |
SEVDESK_API_TOKEN | sevDesk | Accounting API access |
ENCRYPTION_KEY | Internal | Encrypts OAuth tokens at rest (lib/encryption.ts) |
SENTRY_DSN_BACKEND | Sentry | Error reporting endpoint |
BIRD_API_KEY | Bird | SMS API access |
TIGRIS_* | Tigris/S3 | Object storage credentials |
UPSTASH_REDIS_* | Upstash | Redis connection (REST + TCP) |
Authentication Patterns
| Pattern | Used By |
|---|---|
| OAuth 2.0 (authorization code) | HubSpot, DocuSign, Azure Entra |
| API key / token | Bird, Sentry, sevDesk, Resend |
| Access key + secret | Tigris/S3 |
| Connection string | Upstash Redis |
HubSpot and DocuSign OAuth tokens are stored encrypted in the database using ENCRYPTION_KEY (tokens auto-refresh 5 min before expiry). See Library Utilities for the encryption module.
HubSpot Integration Detail
The largest integration — 33 service files (as of 2026-06) under backend/src/services/hubspot/:
| File / Directory | Responsibility |
|---|---|
auth.ts | OAuth token management, automatic refresh |
client.ts | HubSpot API client |
sync-engine/ | Config-driven sync engine; entity-configs.ts holds one EntitySyncConfig per object (canonical entity map) |
event-handlers/ | Webhook event handlers incl. association-handler.ts |
mapping/ | Property/enum mapping |
webhook-handler.ts | Webhook signature validation + dispatch |
hubspot-sync.service.ts | Sync orchestration |
hubspot-sync-admin.service.ts | Admin sync operations |
full-sync.ts, owner-sync.ts | Full re-sync, HubSpot owner sync |
renewa-role-bindings.ts | HubSpot internal_name → Renewa role bindings for associations |
association-config.service.ts, handover-config.service.ts | Association + handover config |
Mirror mapping: HubSpot Deal = R1 projects (no deals table); Listing = buildings; Lead = hubspot_leads. HubSpot-tracked relationships use hubspot_associations + getAssociationsByRenewaName() instead of FK columns (spec 2026-05-08). See HubSpot Integration for full architecture.
Background Processing
Several integrations use Background Jobs (BullMQ + Redis, backend/src/lib/jobs/) for async processing:
| Queue / Processor | Integration |
|---|---|
| Notifications | Resend Email, MessageBird SMS |
| HubSpot sync queue | HubSpot Integration |
| HubSpot webhook event queue | HubSpot Integration |
| HubSpot association reconciliation | HubSpot Integration |
| Entra sync (departments + employees, hourly) | Azure Entra |
| Billing email + sevDesk payment sync | sevDesk, Resend Email |
Related
- Backend Architecture — How integrations fit in the service layer
- Library Utilities — API client implementations
- Services Overview — Service wrappers around integrations
- Deployment Pipeline — Secret flow (Infisical → Fly)
- Secret Management Operations — Operational secret handling
- Security Scanning — Dependency vulnerability scanning