The Integration Built on Prayer: What Happens When Nobody Documents the API
How to inventory, document, and govern every Salesforce integration before one fails silently
The integration works. Nobody knows how. Nobody knows why. The person who built it left the company 18 months ago. The documentation is a Slack message from 2021 that says "should be good now."
I find this pattern in roughly 70% of the orgs I assess.
A nonprofit client called me last year because their donor acknowledgment emails had stopped going out. Donors were giving through Classy, the gifts were appearing in Salesforce, but the automated thank-you emails weren't sending. The development director discovered the problem when a board member mentioned they'd made a $5,000 gift and never received a receipt.
The issue: the Classy-to-Salesforce integration used a connected app that was authenticated with a former employee's credentials. When IT deactivated that employee's Salesforce account during an offboarding process, the connected app lost its authentication token. The integration didn't fail immediately. It failed silently. Donations still synced because a secondary Zapier automation handled the data transfer. The email trigger, which relied on the connected app's webhook, stopped firing.
Three weeks. 847 donations received without acknowledgment. The development team spent 4 days manually sending 847 thank-you emails with correct gift amounts and dates. The cost: $18,000 in labor (across 3 staff members working overtime for a week) plus the reputational impact of 847 donors who wondered whether their gift was received.
The fix took 45 minutes: create a new connected app authenticated with a service account, update the webhook endpoint, test with a $1 test donation. The diagnosis took 3 days because nobody knew which integration handled emails, which handled data sync, or that there were two parallel integrations doing overlapping work.
Why Integration Documentation Gets Skipped
Integrations Are Treated as One-Time Projects
An implementation partner builds an integration as part of a project. The SOW covers "build and deploy." It rarely covers "document and hand off." The partner tests the integration, confirms it works, and moves on. The documentation lives in the developer's head. When the developer leaves the project, the documentation leaves with them.
The Complexity Disincentive
Documenting an integration properly means explaining: what systems it connects, what data moves, in which direction, how often, what authentication method it uses, what error handling exists, and what the failure mode looks like. This takes 30-60 minutes per integration. An org with 8 integrations needs 4-8 hours of documentation work. That work doesn't produce visible features. It gets deprioritized.
"It Just Works"
When an integration runs without errors for months, everyone forgets it exists. It becomes invisible infrastructure. Nobody checks on it because nobody thinks about it. The first time anyone thinks about it is when it breaks.
Credential Ownership Is Informal
Integration credentials (API keys, OAuth tokens, service account passwords) are created by whoever builds the integration. Those credentials are tied to individual accounts rather than service accounts. When the individual leaves, the credentials remain active until they're rotated or the account is deactivated. Nobody tracks which integrations depend on which credentials.
Multiple Tools, No Catalog
An org might use MuleSoft for one integration, Zapier for another, a native Salesforce connection for a third, and a custom Apex callout for a fourth. Each tool has its own monitoring dashboard, its own configuration interface, and its own error notification system. There's no single place to see all integrations together.
How to Inventory Every Integration
The goal is a complete list of every system that sends data to or receives data from your Salesforce org.
Step 1: Check Connected Apps
Navigate to: Setup → Apps → Connected Apps → Manage Connected Apps
This lists every external application that has been granted API access to your Salesforce org. For each connected app, note:
- App name
- Created by (who set it up)
- Connected user (whose credentials are used)
- OAuth scopes (what permissions the app has)
- Last used date (if available)
Flag any connected app where the "Connected User" is a deactivated account. That integration is using dead credentials and will fail when the token expires.
Step 2: Check Named Credentials
Navigate to: Setup → Security → Named Credentials
Named credentials store authentication details for callouts from Salesforce to external systems. For each named credential, document:
- Name and label
- URL (the external endpoint)
- Authentication type (Password, OAuth, JWT)
- Identity type (Named Principal or Per User)
Named credentials connected to external systems that no longer exist are dead metadata. Remove them after confirming no Flows or Apex classes reference them.
Step 3: Check Outbound Messages
Navigate to: Setup → Workflow Actions → Outbound Messages
Outbound messages are a legacy integration method from Workflow Rules. They send SOAP messages to external endpoints when records meet criteria. If your org still uses these, they should be migrated to Flows with HTTP Callout actions or Platform Events.
Step 4: Check Apex Callouts
If your org has custom Apex code, search for HTTP callout references:
Navigate to: Setup → Custom Code → Apex Classes → search for "HttpRequest" or "Http(" in the code
Each Apex class that makes an HTTP callout is an integration. Document the endpoint, the authentication method, and the data being sent or received.
Step 5: Check External Tools
Log into every middleware platform your org uses (MuleSoft, Jitterbit, Zapier, Workato, Informatica) and catalog every flow or integration that connects to your Salesforce instance.
For Zapier: check for Zaps that have "Salesforce" as a trigger or action. For MuleSoft: check for Mule applications with Salesforce connectors.
Step 6: Ask the Team
Send a brief survey to every department: "Does your team use any tool that connects to Salesforce or receives data from Salesforce?" Marketing teams often have integrations (Mailchimp, HubSpot, Pardot) that the Salesforce admin doesn't know about. Finance teams may have ERP integrations. HR may have HRIS connections.
The One-Page Integration Document
Every integration in your org should have a one-page document. One page. Not a 20-page specification. Not a Confluence wiki. One page with these fields:
| Field | Value |
|---|---|
| Integration Name | [Descriptive name] |
| System A | Salesforce |
| System B | [External system] |
| Direction | Salesforce → External / External → Salesforce / Bidirectional |
| Data Transferred | [Specific objects and fields] |
| Frequency | Real-time / Scheduled (specify interval) / Batch (specify schedule) |
| Volume | [Average records per sync] |
| API Type | REST / SOAP / Bulk / Streaming / Webhook |
| Middleware | [MuleSoft / Zapier / Native / Custom Apex] |
| Authentication | [OAuth / API Key / Username-Password / JWT] |
| Credential Type | Service Account / Named User (specify who) |
| Credential Expiry | [Date, or "Does not expire"] |
| Error Handling | [Retry logic / Notification email / Manual check] |
| Monitoring | [Where to check if this integration is running] |
| Primary Contact | [Name, email, phone] |
| Backup Contact | [Name, email, phone] |
| Documentation | [Link to detailed docs if they exist] |
| Last Verified | [Date someone confirmed this integration is working] |
Failure Scenario (bottom of page):
- If this integration stops working, what business process is affected?
- Who should be notified first?
- What is the manual workaround while the integration is down?
- What is the estimated time to repair?
That's it. One page. Filling this out for a single integration takes 10-15 minutes. The 10-15 minutes prevents the 3-day diagnostic hunt and the $18,000 cleanup.
How to Fix Integration Problems
Replace Personal Credentials with Service Accounts
Every integration should authenticate using a dedicated service account, not a named user's credentials. Create an integration user in Salesforce:
Navigate to: Setup → Users → New User
Set up the user with:
- Profile: a custom profile with only the permissions the integration needs
- Permission Set: integration-specific permissions
- Username: integration@yourorg.com (descriptive, not personal)
- No password expiration (or manage rotation through your identity provider)
Update every connected app and integration to use this service account. When employees leave, integrations continue working because they don't depend on any individual's account.
Add Error Notification
Every integration should notify someone when it fails. The notification method depends on the integration type:
For Zapier: enable error notifications in Zap settings (Settings → Notifications → Notify when Zap errors).
For custom Apex callouts: add a try-catch block that creates a custom object record or sends an email to the admin when a callout fails:
try {
HttpResponse res \= http.send(req);} catch (Exception e) {
Integration\_Error\_\_c error \= new Integration\_Error\_\_c();
error.Error\_Message\_\_c \= e.getMessage();
error.Integration\_Name\_\_c \= 'Classy Donation Sync';
error.Occurred\_At\_\_c \= Datetime.now();
insert error;}
For MuleSoft/middleware: configure error handling flows that send alerts via email or Slack when a process fails.
Establish Retry Logic
Integrations fail temporarily due to network timeouts, API rate limits, and service outages. Retry logic handles these transient failures automatically:
- Retry 3 times with exponential backoff (wait 1 second, then 5 seconds, then 30 seconds)
- After 3 retries, log the error and notify the admin
- Do not retry indefinitely. Infinite retries on a permanent failure create an API call loop that consumes governor limits.
How to Prevent Integration Failures
Quarterly credential review: Every quarter, check every connected app and named credential. Verify the authenticating user is active. Verify the credential hasn't expired. Verify the external system endpoint is still valid.
Integration ownership assignment: Every integration has a named owner. That person is responsible for monitoring, credential rotation, and documentation updates. When the owner changes roles or leaves, ownership transfers as part of the offboarding process.
Monthly health check: Run a monthly check of every integration. Did data sync successfully in the last 30 days? Are error logs clean? Are retry queues empty? This takes 30 minutes per month and catches silent failures before they become 3-week data gaps.
Onboarding/offboarding integration check: Add to your employee onboarding and offboarding checklists: "Check for integrations authenticated with this user's credentials." This prevents the credential death spiral where deactivating a user's account silently breaks an integration nobody knew depended on that user.
Download the Integration Documentation Template
The Integration Documentation Template is an editable document with the one-page format for every integration, pre-filled field labels, and a failure scenario section. Print one copy per integration. Fill it out. Store them in a shared location. Update them when anything changes.
Download it below. It's free.
Part 7 of 10 in the series: What Your Salesforce Org Says About Your Company.
