Integration Schema

Purpose: External service integrations, health data exchange, and API management Tenant Scoped: Yes (all tables) RLS Enabled: Yes

Overview

The integration schema manages connections to external systems including:

ABDM (Ayushman Bharat Digital Mission) for India
Health data exchange protocols
Webhook management
API logging and rate limiting

Entities

ABDM Integration (India)

Entity: AbdmRecord

Purpose: ABDM health records linked to patients

Attributes:

Attribute	Type	Required	Description
id	UUID	Yes	Primary identifier
tenant_id	UUID	Yes	Owning tenant
patient_id	UUID	Yes	Patient reference
abha_id	String	Yes	ABHA identifier
record_type	Enum	Yes	prescription, diagnostic_report, discharge_summary, op_consult
hip_id	String	Yes	Health Information Provider ID
care_context_id	String	Yes	ABDM care context reference
transaction_id	String	No	ABDM transaction ID
request_id	String	No	ABDM request ID
status	Enum	Yes	pending, fetched, linked, error
fhir_bundle	JSONB	No	FHIR bundle data
raw_response	JSONB	No	Raw ABDM response
linked_encounter_id	UUID	No	Linked encounter
fetched_at	Timestamp	No	When fetched
expires_at	Timestamp	No	Record expiry
error_message	Text	No	Error details
created_at	Timestamp	Yes	Creation time

Record Types:

prescription - Prescription records
diagnostic_report - Lab/imaging reports
discharge_summary - Hospital discharge summary
op_consult - Outpatient consultation record
immunization - Immunization records
health_document - Other health documents

Relationships:

Belongs to: Tenant, Patient, Encounter

Entity: AbdmConsent

Purpose: ABDM consent artifacts

Attributes:

Attribute	Type	Required	Description
id	UUID	Yes	Primary identifier
tenant_id	UUID	Yes	Owning tenant
patient_id	UUID	Yes	Patient reference
abha_id	String	Yes	ABHA identifier
consent_id	String	Yes	ABDM consent ID
consent_status	Enum	Yes	requested, granted, denied, revoked, expired
purpose	Enum	Yes	care_management, break_the_glass, public_health, healthcare_payment
hi_types	String[]	Yes	Health information types
requester_hip_id	String	Yes	Requesting HIP
date_range_from	Date	No	Data from date
date_range_to	Date	No	Data to date
consent_expiry	Timestamp	No	Consent expiry
granted_at	Timestamp	No	When granted
revoked_at	Timestamp	No	When revoked
created_at	Timestamp	Yes	Request time

HI Types:

["Prescription", "DiagnosticReport", "DischargeSummary", "OPConsultation", "Immunization", "HealthDocument"]

Purpose Values:

care_management - Regular care delivery
break_the_glass - Emergency access
public_health - Public health purposes
healthcare_payment - Insurance/payment

Relationships:

Belongs to: Tenant, Patient
Has many: AbdmRecords

Entity: AbdmCallback

Purpose: ABDM callback events log

Attributes:

Attribute	Type	Required	Description
id	UUID	Yes	Primary identifier
tenant_id	UUID	Yes	Owning tenant
callback_type	String	Yes	Callback endpoint type
request_id	String	No	ABDM request ID
transaction_id	String	No	ABDM transaction ID
payload	JSONB	Yes	Callback payload
status	Enum	Yes	received, processing, processed, failed
error_message	Text	No	Processing error
received_at	Timestamp	Yes	Receipt time
processed_at	Timestamp	No	Processing time

Callback Types:

consent-request/on-init
consent-request/on-status
health-information/on-request
health-information/hip/on-request
links/link/on-init
links/link/on-confirm

Relationships:

Belongs to: Tenant

Health Information Exchange

Entity: ExternalRecord

Purpose: Health records from external systems (non-ABDM)

Attributes:

Attribute	Type	Required	Description
id	UUID	Yes	Primary identifier
tenant_id	UUID	Yes	Owning tenant
patient_id	UUID	Yes	Patient reference
source_system	String	Yes	Source system name
source_id	String	No	External record ID
record_type	Enum	Yes	lab_result, imaging, prescription, document
fhir_resource_type	String	No	FHIR resource type
content	JSONB	Yes	Record content
raw_data	JSONB	No	Original format data
received_at	Timestamp	Yes	When received
processed	Boolean	No	Processing complete
linked_resource_id	UUID	No	Created clinical resource
linked_resource_type	String	No	Type of linked resource

Relationships:

Belongs to: Tenant, Patient

Webhook Management

Entity: WebhookEndpoint

Purpose: Registered webhook endpoints for external systems

Attributes:

Attribute	Type	Required	Description
id	UUID	Yes	Primary identifier
tenant_id	UUID	Yes	Owning tenant
name	String	Yes	Endpoint name
url	String	Yes	Webhook URL
secret	String	No	Signing secret (encrypted)
events	String[]	Yes	Subscribed events
status	Enum	Yes	active, paused, disabled
version	String	No	API version
headers	JSONB	No	Custom headers
retry_policy	JSONB	No	Retry configuration
created_by_id	UUID	Yes	Creator user
last_triggered_at	Timestamp	No	Last trigger time
failure_count	Integer	No	Consecutive failures
created_at	Timestamp	Yes	Creation time

Events:

["patient.created", "appointment.scheduled", "appointment.cancelled",
 "encounter.completed", "prescription.created", "invoice.paid"]

Retry Policy Structure:

{
  "max_retries": 3,
  "retry_delay_seconds": 60,
  "exponential_backoff": true
}

Relationships:

Belongs to: Tenant, User
Has many: WebhookEvents

Entity: WebhookEvent

Purpose: Webhook delivery attempts

Attributes:

Attribute	Type	Required	Description
id	UUID	Yes	Primary identifier
tenant_id	UUID	Yes	Owning tenant
endpoint_id	UUID	Yes	Target endpoint
event_type	String	Yes	Event type
payload	JSONB	Yes	Event payload
status	Enum	Yes	pending, delivered, failed, cancelled
attempts	Integer	No	Delivery attempts
last_attempt_at	Timestamp	No	Last attempt time
next_retry_at	Timestamp	No	Next retry time
response_status	Integer	No	HTTP response status
response_body	Text	No	Response body (truncated)
error_message	Text	No	Error details
created_at	Timestamp	Yes	Event creation
delivered_at	Timestamp	No	Successful delivery

Relationships:

Belongs to: Tenant, WebhookEndpoint

API Management

Entity: ApiKey

Purpose: API keys for external access

Attributes:

Attribute	Type	Required	Description
id	UUID	Yes	Primary identifier
tenant_id	UUID	Yes	Owning tenant
name	String	Yes	Key name
key_hash	String	Yes	Hashed API key
key_prefix	String	Yes	Key prefix for identification
scopes	String[]	Yes	Permitted scopes
rate_limit	Integer	No	Requests per minute
status	Enum	Yes	active, revoked
expires_at	Timestamp	No	Expiration time
last_used_at	Timestamp	No	Last usage
created_by_id	UUID	Yes	Creator user
revoked_at	Timestamp	No	Revocation time
revoked_by_id	UUID	No	Revoking user
created_at	Timestamp	Yes	Creation time

Scopes:

["patients:read", "patients:write", "appointments:read", "appointments:write",
 "encounters:read", "reports:read", "billing:read"]

Relationships:

Belongs to: Tenant, User

Entity: ApiLog

Purpose: API request/response logging

Attributes:

Attribute	Type	Required	Description
id	UUID	Yes	Primary identifier
tenant_id	UUID	Yes	Owning tenant
api_key_id	UUID	No	API key used
user_id	UUID	No	User if authenticated
method	String	Yes	HTTP method
path	String	Yes	Request path
query_params	JSONB	No	Query parameters
request_headers	JSONB	No	Request headers (filtered)
request_body	JSONB	No	Request body (filtered)
response_status	Integer	Yes	Response status code
response_time_ms	Integer	No	Response time
ip_address	String	No	Client IP
user_agent	String	No	User agent
error_message	Text	No	Error if any
created_at	Timestamp	Yes	Request time

Note: Sensitive data (tokens, passwords, PII) is filtered from logs.

Relationships:

Belongs to: Tenant, ApiKey, User

Schema Diagram

+---------------+       +---------------+       +---------------+
| abdm_records  |       | abdm_consents |       | abdm_callbacks|
+---------------+       +---------------+       +---------------+
       |                       |
       v                       v
+------------------------------------------+
|              clinical.patients           |
+------------------------------------------+

+---------------+       +---------------+
| external_     |       | webhook_      |
| records       |       | endpoints     |
+---------------+       +---------------+
                               |
                               v
                        +---------------+
                        | webhook_events|
                        +---------------+

+---------------+       +---------------+
|   api_keys    |------>|   api_logs    |
+---------------+       +---------------+

ABDM Integration Flow

1. Patient Links ABHA
   Patient --> AbdmConsent (requested) --> ABDM Gateway

2. Consent Granted
   ABDM Gateway --> AbdmCallback --> AbdmConsent (granted)

3. Health Data Fetch
   AbdmConsent --> AbdmRecord (pending) --> ABDM Gateway

4. Data Received
   ABDM Gateway --> AbdmCallback --> AbdmRecord (fetched)
   AbdmRecord --> clinical.* resources (linked)

RLS Policies

-- All integration tables: tenant isolation
CREATE POLICY tenant_isolation ON integration.abdm_records
    USING (tenant_id = current_setting('app.current_tenant_id')::uuid);

CREATE POLICY tenant_isolation ON integration.webhook_endpoints
    USING (tenant_id = current_setting('app.current_tenant_id')::uuid);

CREATE POLICY tenant_isolation ON integration.api_keys
    USING (tenant_id = current_setting('app.current_tenant_id')::uuid);

Security Considerations

API Keys: Stored as hashed values, never in plaintext
Webhook Secrets: Encrypted at rest
ABDM Data: Follows ABDM data protection guidelines
API Logs: PII and sensitive data filtered before storage
Consent Management: Strict consent lifecycle enforcement

Integration Schema

OverviewCopy Anchor Link

EntitiesCopy Anchor Link

ABDM Integration (India)Copy Anchor Link

Entity: AbdmRecordCopy Anchor Link

Entity: AbdmConsentCopy Anchor Link

Entity: AbdmCallbackCopy Anchor Link

Health Information ExchangeCopy Anchor Link

Entity: ExternalRecordCopy Anchor Link

Webhook ManagementCopy Anchor Link

Entity: WebhookEndpointCopy Anchor Link

Entity: WebhookEventCopy Anchor Link

API ManagementCopy Anchor Link

Entity: ApiKeyCopy Anchor Link

Entity: ApiLogCopy Anchor Link

Schema DiagramCopy Anchor Link

ABDM Integration FlowCopy Anchor Link

RLS PoliciesCopy Anchor Link

Security ConsiderationsCopy Anchor Link

On this page

Overview

Entities

ABDM Integration (India)

Entity: AbdmRecord

Entity: AbdmConsent

Entity: AbdmCallback

Health Information Exchange

Entity: ExternalRecord

Webhook Management

Entity: WebhookEndpoint

Entity: WebhookEvent

API Management

Entity: ApiKey

Entity: ApiLog

Schema Diagram

ABDM Integration Flow

RLS Policies

Security Considerations