Integrations

This directory contains documentation for all third-party service integrations and external API connections used throughout the Kulcare platform.

Integration CategoriesCopy Anchor Link

Communication ServicesCopy Anchor Link

• SMS & Voice - SMS delivery via MSG91, Twilio, and voice services
• WhatsApp - WhatsApp messaging via WATI API with delivery tracking
• Push Notifications - Mobile push notifications via AWS SNS
• Email Services - Transactional emails and campaign management

Healthcare & ComplianceCopy Anchor Link

• ABDM Integration - India's Ayushman Bharat Digital Mission
• FHIR Compliance - Healthcare data exchange standards
• Medical APIs - Drug databases, medical coding systems

Payment & BillingCopy Anchor Link

• Razorpay - Payment gateway for subscriptions and transactions
• Financial APIs - Banking integrations and financial reporting

Analytics & MarketingCopy Anchor Link

• Analytics Services - Mixpanel, Google Analytics, tracking
• Marketing Automation - Baserow, campaign management
• Google Services - Google My Business, Maps, OAuth

Infrastructure & CloudCopy Anchor Link

• AWS Services - S3, SNS, CloudWatch, and other AWS integrations
• ElasticSearch - Search and indexing services
• Background Jobs - Sidekiq and job processing

Development & MonitoringCopy Anchor Link

• Error Tracking - Sentry, logging, and error monitoring
• API Documentation - External API integrations and webhooks
• Testing Services - Testing environments and mock services

Quick ReferenceCopy Anchor Link

Active IntegrationsCopy Anchor Link

Integration PatternsCopy Anchor Link

Background Job ProcessingCopy Anchor Link

Most external API calls are processed asynchronously using Sidekiq:

# Standard pattern for external API integration
class ExternalApiService < ActiveJob::Base
  queue_as :external_apis
  
  def perform(params)
    # API call logic
    # Error handling
    # Logging
  end
end

Webhook HandlingCopy Anchor Link

External services send webhooks to dedicated controllers:

class ExternalWebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token
  
  def create
    # Verify webhook signature
    # Process webhook data
    # Return appropriate response
  end
end

Configuration ManagementCopy Anchor Link

All integration credentials are stored securely:

# Credentials access pattern
Rails.application.credentials.service_name.api_key
Rails.application.credentials.service_name.webhook_secret

Error HandlingCopy Anchor Link

Standardized error handling for external integrations:

begin
  external_api_call
rescue StandardError => e
  Rails.logger.error "Integration Error: #{e.message}"
  ErrorTrackingService.notify(e)
  # Graceful degradation logic
end

Integration Health MonitoringCopy Anchor Link

Health Check EndpointsCopy Anchor Link

Each integration should implement health check endpoints:

def health_check
  {
    service_name: {
      status: 'healthy|degraded|down',
      last_success: timestamp,
      last_error: error_message,
      response_time: milliseconds
    }
  }
end

Monitoring AlertsCopy Anchor Link

Set up monitoring for:

• API response times
• Error rates
• Webhook delivery failures
• Service unavailability
• Rate limit violations

Security ConsiderationsCopy Anchor Link

API Key ManagementCopy Anchor Link

• Store all credentials in Rails encrypted credentials
• Rotate keys regularly
• Use environment-specific keys
• Monitor key usage and access

Webhook SecurityCopy Anchor Link

• Verify webhook signatures
• Use HTTPS endpoints only
• Implement rate limiting
• Log all webhook requests

Data PrivacyCopy Anchor Link

• Minimize data shared with third parties
• Comply with HIPAA/GDPR requirements
• Audit data access and sharing
• Implement data retention policies

Development GuidelinesCopy Anchor Link

Adding New IntegrationsCopy Anchor Link

1. Create integration documentation
2. Implement service classes with error handling
3. Add configuration to credentials
4. Create background jobs for async processing
5. Implement webhook handlers if needed
6. Add monitoring and health checks
7. Write comprehensive tests
8. Update this documentation

Testing IntegrationsCopy Anchor Link

• Use VCR for recording HTTP interactions
• Mock external APIs in test environment
• Test error scenarios and edge cases
• Validate webhook signature verification
• Test rate limiting and retry logic

Documentation StandardsCopy Anchor Link

Each integration should document:

• Service overview and purpose
• Authentication and configuration
• API endpoints and data formats
• Error handling and retry logic
• Rate limits and quotas
• Webhook specifications
• Testing approaches
• Troubleshooting guides

Related DocumentationCopy Anchor Link

• Development Guide - Testing external integrations
• Deployment Guide - Environment configuration
• Background Jobs - Sidekiq and job processing
• Monitoring - System monitoring and alerts