PeopleHub Documentation

Integration Landscape ​

External System Integrations ​

PeopleHub integrates with external systems for recruitment, e-signature, and future payroll/workforce management capabilities.

Current Integrations ​

Digio (E-Signature Platform) ​

Purpose: Digital signature for onboarding policies and agreements

Integration Type: Webhook-based

Flow:

  1. Candidate API creates signature request in Digio
  2. Digio sends email to candidate with sign link
  3. Candidate signs document on Digio platform
  4. Digio sends webhook to PeopleHub Integration API
  5. Integration API updates document status in database
  6. Notification sent to HR team

Endpoints:

  • Outbound: Digio API (create signature request)
  • Inbound: /webhooks/digio (receives status updates)

Authentication:

  • Client ID and Client Secret for API calls
  • Webhook secret for validating incoming webhooks

Documents Signed:

  • Employment policies
  • Code of conduct
  • Background verification consent
  • Offer letter acceptance

TalentRecruit (ATS Integration) ​

Purpose: Applicant Tracking System for recruitment

Integration Type: API-based (planned)

Planned Flow:

  • Fetch candidate data from TalentRecruit
  • Sync to PeopleHub recruitment module
  • Update candidate status back to TalentRecruit

Status: Design phase

Planned Integrations ​

Payroll Systems ​

Purpose: Sync employee and salary data for payroll processing

Integration Type: Scheduled sync (daily/weekly)

Data Flow:

  • Outbound: Employee master data, attendance, leave records
  • Inbound: Salary structure, payment details

Status: Requirements gathering

Workforce Management Systems ​

Purpose: Project time tracking and resource allocation

Integration Type: Real-time API sync

Data Flow:

  • Outbound: Employee details, project allocations
  • Inbound: Timesheet data, project hours

Status: Planned for future phase

Learning Management System (LMS) ​

Purpose: Training and development tracking

Integration Type: SSO + API

Data Flow:

  • Outbound: Employee details for SSO
  • Inbound: Training completion status, certifications

Status: Future consideration

Background Verification Vendors ​

Purpose: Automated background checks for new hires

Integration Type: API-based

Status: Under evaluation

Integration Architecture ​

Integration API Service ​

Centralized service handling all external integrations:

  • Webhook endpoints for inbound data
  • API clients for outbound calls
  • Scheduled jobs for periodic syncs
  • Error handling and retry logic

Tech Stack: Node.js 20, Fastify, Drizzle ORM

Integration Patterns ​

Webhook Pattern (Digio):

  • External system pushes events to PeopleHub
  • Validates webhook signature
  • Processes event asynchronously
  • Logs all webhook events for audit

Polling Pattern (ATS - planned):

  • Scheduled Lambda (cron) fetches data from external system
  • Compares with existing data
  • Updates/creates records as needed
  • Logs sync status

Real-Time API Pattern (Workforce Management - planned):

  • Event in PeopleHub triggers immediate API call to external system
  • Synchronous response expected
  • Retry logic for failures

Data Mapping ​

Each integration has:

  • Field Mapping: PeopleHub fields ↔ External system fields
  • Data Transformation: Format conversion, validation
  • Conflict Resolution: Rules for handling data conflicts

Security ​

API Authentication ​

  • API keys stored in AWS Secrets Manager
  • Automatic rotation every 30 days
  • Per-integration credentials

Webhook Validation ​

  • Signature verification using shared secret
  • IP whitelisting (where supported)
  • Request logging for audit

Data Encryption ​

  • HTTPS/TLS for all API communication
  • No sensitive data in logs
  • PII data encrypted before transmission (where applicable)

Error Handling ​

Retry Strategy ​

  • Exponential backoff for transient failures
  • Max 3 retries for API calls
  • Dead letter queue for failed webhooks

Monitoring ​

  • CloudWatch alarms for integration failures
  • Daily sync status reports
  • Error notifications to dev team

Integration Endpoints ​

Inbound Webhooks ​

  • POST /webhooks/digio - Digio e-signature events
  • POST /webhooks/ats - ATS candidate updates (planned)
  • POST /webhooks/payroll - Payroll sync events (planned)

Outbound API Calls ​

  • Digio API: https://api.digio.in/v2/
  • TalentRecruit API: TBD
  • Payroll API: TBD

Scheduled Jobs ​

Cron jobs running in Integration API Lambda:

Daily Jobs:

  • Sync ATS candidates (planned)
  • Send employee data to payroll (planned)
  • Data cleanup and archival

Weekly Jobs:

  • Generate integration health reports
  • Reconcile data between systems

Future Considerations ​

Azure SSO Integration ​

Currently using custom JWT authentication. Future plan to integrate with client's Azure Active Directory for single sign-on.

Benefits:

  • Centralized user management
  • Enterprise security policies
  • Multi-factor authentication

Timeline: Post initial deployment

API Gateway for External Access ​

Future possibility to expose PeopleHub APIs for client's other systems:

  • Read-only access to employee data
  • Leave balance queries
  • Attendance data export

Security: API key + IP whitelisting

Integration Testing ​

Sandbox Environments:

  • Digio provides test environment for signature testing
  • Other integrations will use sandbox/test APIs before production

Test Data:

  • Synthetic test data for integration testing
  • No production data in test environments