Documenting Integrations Before the Developer Leaves
By CodexierPublished 4 min read
The webshop sends orders to Fortnox, the website form creates deals in the CRM, a nightly job updates stock. It all works, until the freelancer who built it moves on and a password expires. Then nobody knows where the integration runs, which account it uses or what it was supposed to do. This guide gives you a one-page template per integration and a routine to keep it current.
Why integration knowledge disappears
Integrations sit between systems, so nobody owns them naturally. The CRM vendor supports the CRM, the accountant knows Fortnox, but the glue in between lives in one person's head and one person's accounts. It runs silently for months, so nobody thinks about it. When it breaks, often because a token expired, an API changed or a card on the hosting account lapsed, the knowledge needed to fix it has gone.
A one-page template per integration
| Field | What to write |
|---|---|
| Name and purpose | One sentence: what business problem it solves |
| Systems involved | Source and destination, such as Shopify to Fortnox |
| Data flow | What data moves, in which direction, and what triggers it |
| Where it runs | Automation tool, serverless function, server or plugin, with a link |
| Schedule or trigger | Real time via webhook, every hour, nightly |
| Credentials | Which accounts and keys it uses, and where they are stored |
| Dependencies | Paid services, API versions, anything that expires |
| Failure handling | What happens when it fails and who is alerted |
| Owner | Business owner and technical contact |
| Last reviewed | Date and by whom |
Add a simple diagram if it helps: boxes for systems and arrows for data. A photo of a whiteboard sketch is fine.
Credentials and where they live
The most common crisis is not code but access. The integration runs on the developer's personal Zapier or Make account, the API key was created in their name, or the hosting is billed to their card.
- Move every automation tool account, cloud account and domain to company ownership, with at least two admins.
- Create API keys under a service account or company user, not a person.
- Store keys and passwords in a shared vault in a business password manager.
- Note expiry dates for tokens and certificates in a shared calendar.
- When someone leaves, rotate the keys they had access to.
Failure scenarios and fixes
Token or password expired
Symptom: nothing arrives, or errors in the log. Fix: renew the credential in the vault and reconnect. Note how on the page.
API changed
Symptom: partial data or new errors after a vendor update. Fix: update the mapping; the page should say which API version is used.
Duplicate or missing records
Symptom: two invoices for one order, or a gap. Fix: know where to look and how to rerun safely without duplicates.
Billing lapsed
Symptom: the whole tool stops. Fix: company card on every service, and billing emails to a shared address.
For each integration, write how a non-developer can tell it is working, for example that yesterday's orders are in Fortnox, and set up an alert when it is not. Our guide to webhooks or scheduled sync explains why the answer differs by integration type.
Owners and review dates
- Give each integration a business owner who notices when the outcome is wrong.
- Name a technical contact, internal or an agency, with a support agreement if it is critical.
- Review every page twice a year: still needed, still correct, credentials still valid?
- Update the page as part of any change, not afterwards.
- Keep all pages in one shared place that survives staff changes.
When you do not need help: if you have two or three simple integrations and the builder is still reachable, a few hours with them and this template is enough. If the knowledge has already gone, or you have many connections nobody fully understands, our integration and automation optimisation maps and documents them. See the pricing page or book a short call.
Frequently asked questions
The developer has already left. Where do we start?
List the systems you know exchange data, then check each for connected apps, API keys and automation accounts. Billing records and old emails often reveal tools you forgot. Regain admin access first, then document.
How detailed should the documentation be?
Detailed enough that a competent developer who has never seen it could find it, understand its purpose and fix a common failure. One page per integration usually achieves that; code-level detail belongs in the code repository.
Where should we keep integration documentation?
In a shared company space such as a wiki, a shared drive or your ticket system, not in a personal document. Credentials go in the password manager, with the page pointing to them.
Should the agency that built it write the documentation?
Yes, ideally as part of the delivery. Ask for it in the contract, including a handover of all accounts and keys to the company.
Map your integrations before they break
List the systems you think are connected. In 15 minutes we will help you identify the risky ones and what to document first.
Book a free 15-minute call