1. Overview
The Alleva EMR Webhook Integration extends the existing bi-directional data sync between your InsightsTx / AllevaCRM instance and the Alleva EMR. Instead of relying solely on scheduled cron jobs to pull data, this feature allows Alleva to push real-time notifications to the CRM the moment a patient record is created, updated, or discharged — typically synchronising within seconds.
1.1 Supported Webhook Events
CLIENT_CREATE — A new patient is created in Alleva. The CRM either matches an existing Opportunity or creates a new One.
CLIENT_UPDATE — A patient record is modified in Alleva. The CRM updates the linked Opportunity.
CLIENT_DISCHARGE — A patient is discharged in Alleva. The CRM updates status, discharge date, and discharge type.
2. Prerequisites
Confirm the following before configuring webhooks:
1. Your CRM instance is live and reachable over HTTPS from the public internet.
2. The Alleva EMR integration is already connected — valid API credentials exist in CRM EMR Settings.
3. You have Administrator access to both the CRM and the Alleva portal.
4. The CRM system user 'insightstx_EMR' exists (it performs all automated EMR record updates).
5. Data sharing is configured to allow data to flow from Alleva into the CRM.
3. Step-by-Step Setup
Step 1 — Verify Your Alleva EMR Connection in the CRM
The webhook endpoint authenticates requests using the Secret Key stored in CRM EMR Settings. Confirm it is present before registering the webhook in Alleva.
Log in to the CRM as an Administrator.
Go to: Settings > EMR Settings > Alleva.
Confirm the following credentials are filled in: Access ID, Client ID (Recipient ID), Secret Key.
Click 'Test Connection'. Status must show Connected. Resolve any errors before continuing.
Note: Copy the Secret Key now — you will paste it into the Alleva portal in Step 3. It must match
exactly.
Step 2 — Identify Your Webhook Endpoint URL
The CRM exposes a dedicated webhook receiver at:
Example for an AllevaCRM instance:
Note: The endpoint accepts only HTTP POST requests over HTTPS. Any other method is rejected immediately.
Step 3 — Register the Webhook in the Alleva Portal
This step is performed in the Alleva EMR system by someone with Alleva administrator access.
Log in to the Alleva EMR portal.
Navigate to your facility's integration or webhook settings.
Add a new webhook with the following values:
Webhook URL: https://<your-instance-domain>/crm/AllevaWebhook.php
Set Up the HTTP Secret Key
1. In the webhook settings, look for an option to add custom headers.
2. Add a custom header with the following details:
- **Header Name**: `SECRET_KEY`
- **Header Value**: `<Your_Secret_Key>`
> Replace `<Your_Secret_Key>` with the API secret key being used for any of the Alleva account saved in the CRM.
Events: CLIENT_CREATE, CLIENT_UPDATE, CLIENT_DISCHARGE
Save the webhook configuration in Alleva.
Trigger a test event and verify the CRM receives it (see Section 5 — Verification).
Warning: The Secret Key is sensitive. Treat it like a password. If it is ever compromised, generate a new one in CRM EMR Settings and update the Alleva portal immediately.
Step 4 — Configure EMR Default Settings in the CRM
These settings control what data flows into the CRM when a webhook event is received.
Navigate to: Settings > EMR Settings > Default Settings.
4a. Data Sharing Direction
Both — Data flows in both directions (CRM <> Alleva).
EHR to CRM — Data flows only from Alleva into the CRM (recommended for webhook use).
CRM to EHR — Data flows only from the CRM into Alleva.
4b. Update CRM Action
Select which patient fields can be written to the CRM on an update:
patient_name — Sync first and last name to the CRM Contact.
DOB — Sync date of birth to the CRM Contact.
other_demographic — Sync all other mapped demographic fields.
opportunity_information — Sync Opportunity-level data (admission date, LOC, facility, etc.).
4c. Contacts and Insurance Pull
emergency_contacts — Create or update emergency contact records linked to the patient.
insurance — Create or update insurance policy records using Alleva's insurance API.
4d. Level of Care History
loc_hx — Create a LOC History entry each time the patient's Level of Care changes.
4e. Transfer / Re-Admit
When enabled, the CRM creates a new Opportunity (and Contact if needed) for a patient that cannot be matched to an existing CRM record. Disable this if you want the CRM to only update existing matched records.
4f. Outbound Referrals
When enabled, the CRM automatically creates an Outbound Referral on patient discharge if Alleva returns a discharge destination.
Step 5 — Verify Field Mapping
The field mapping table translates Alleva API field names into CRM field names. Confirm mappings are correct for your instance.
Go to: Settings > EMR Settings > Field Mapping > Alleva.
Review mappings for: Intake Opportunities, Contacts, Insurances, and Bedboards.
Pay special attention to: Admission Date, Discharge Date, Level of Care, Facility, and Status.
Note: Mismatched field mappings will write data to the wrong CRM field. Test with a real patient record before going live.
Step 6 — Verify Value Mapping
The CRM translates Alleva's raw text values into your CRM picklist values. Go to: Settings > EMR Settings > Value Mapping > Alleva.
Review the following mapping types:
Type 1 — Admitted Type / Status
Type 2 — Level of Care
Type 3 — Location / Facility Name
Type 5 — Discharge Type
Note: If Alleva sends a value with no mapping, the CRM falls back to the existing CRM value or leaves the field blank. Add missing mappings to ensure complete synchronization.
4. How the Webhook Works
4.1 Request Authentication
Every request Alleva sends must include a custom HTTP header:
secret_key: <your configured secret key>
The CRM validates this against the value in EMR Settings. If missing or incorrect, the request is rejected and nothing is written to the database.
4.2 Event Routing
The CRM reads two fields from the JSON payload: id (the Alleva casefile ID) and event_type.
CLIENT_CREATE: Calls Alleva GET /clients/{id}, then attempts to match an existing Opportunity by name + DOB + facility + admission date. If matched, it links the records. If not matched and Transfer/Re-Admit is enabled, it creates a new Contact and Opportunity.
CLIENT_UPDATE / CLIENT_DISCHARGE: Looks up the existing EMR map record, calls Alleva GET /clients/{id}, and updates the linked Opportunity with the latest admission/discharge data, status, LOC, and MRN.
4.3 Immediate Acknowledgement
The endpoint returns HTTP 200 'OK' to Alleva as soon as authentication passes — before the full sync completes. This prevents Alleva from timing out while the CRM performs its API calls and database updates.
5. Verifying the Setup
5.1 Trigger a Test Event
In the Alleva portal, make a minor change to a test patient (e.g., update a phone number) to fire a CLIENT_UPDATE event.
Wait 5–10 seconds.
Open the corresponding CRM Opportunity and confirm the Modified Time has updated.
6. Troubleshooting
6.1 Webhook Calls Are Not Arriving
Confirm the URL in Alleva is correct: https://<domain>/crm/AllevaWebhook.php
Confirm the CRM domain is publicly accessible over HTTPS.
Check the Alleva portal's webhook delivery log for error responses.
Verify the server firewall / WAF allows inbound POST requests to the webhook path.
6.2 'Invalid secret key' Error
The secret_key header from Alleva does not match the CRM EMR Settings value.
Copy the exact Secret Key from CRM Settings and re-paste it into the Alleva portal.
Check for leading/trailing spaces in either value.
6.3 Webhook Arrives But Opportunity Not Updated
Verify Data Sharing Direction is 'Both' or 'EHR to CRM'.
Confirm Alleva connection is active via 'Test Connection'.
Confirm the casefile_id in the payload exists in vtiger_opportunities_emr_map.
6.4 Wrong Data Written to Opportunity
Check Field Mapping for mismatched field names.
Check Value Mapping for unmapped picklist values.
Verify the required Update CRM Action options are enabled (Section 4b).
6.5 Duplicate Records Being Created
The CRM creates new records only when no match is found by name + DOB + facility + admission date.
Ensure these four fields are consistent between existing CRM records and Alleva data.
Disable 'Transfer / Re-Admit' if you do not want new records auto-created.
7. Security Considerations
The Secret Key is the sole authentication mechanism. Rotate it immediately if ever exposed.
All webhook traffic must travel over HTTPS — never plain HTTP.
The CRM validates the Secret Key on every request before any database operation.
Webhook payloads (including headers) are stored in full — restrict database access to authorized personnel.
The 'insightstx_EMR' CRM user performs all automated updates. Do not delete or deactivate it.
8. Quick Reference Checklist
[ ] CRM instance live on HTTPS
[ ] Alleva API credentials saved in CRM EMR Settings
[ ] 'Test Connection' passes in CRM EMR Settings
[ ] Webhook URL registered in Alleva portal
[ ] Secret Key in Alleva portal matches CRM EMR Settings
[ ] Alleva subscribed to: CLIENT_CREATE, CLIENT_UPDATE, CLIENT_DISCHARGE
[ ] Data Sharing Direction = 'Both' or 'EHR to CRM'
[ ] Required Update CRM Action options enabled
[ ] Field Mapping reviewed and confirmed
[ ] Value Mapping reviewed for Status, LOC, Location, Discharge Type
[ ] Test event triggered and Opportunity updated correctly
9. Support
If issues cannot be resolved with this guide, contact InsightsTx / AllevaCRM support and provide:
Your CRM instance domain
The Alleva case file ID of the patient record that failed to sync