The core distinction
Connected is not the same as integrated.
A connection means data can move between two systems. An integration means the data that moves is trustworthy, complete, and arrives in a form the receiving system can act on without additional handling. Most organisations have many connections and very few integrations in this second sense. The distinction matters because the failure modes are completely different. A broken connection stops data from moving - it is immediately visible. A broken integration lets data keep moving in the wrong shape - it is invisible until something downstream fails, often weeks or months after the problem began.
Where integrations fail
Integration problems are predictable. They cluster in four places.
Understanding where your integration is most likely to break is the first step to building one that does not. These four failure categories cover the majority of operational integration problems across different tools and business contexts.
Failure 1
Data format mismatch at the boundary
The sending system uses a date format the receiving system does not recognise. A status field contains values that mean something in system A and nothing in system B. A required field in the destination is optional in the source and sometimes arrives empty.
Format mismatches are the most common and the most preventable integration failure. They happen because the integration was built against an example record rather than against a formal definition of what the data can contain. The fix is defining the data contract before building the connection: every field that will pass between systems, its type, its allowed values, its behaviour when missing.
Failure 2
Missing ownership of the gap
When data moves between systems, errors and exceptions will occur. Records that fail validation. Events that arrive out of order. Duplicates created by timing edge cases. Every integration produces a gap - situations the integration does not handle automatically - and if nobody owns that gap, it fills with manual workarounds.
The ownership question needs to be answered before launch: when this integration fails for a specific record, what happens? Who is notified? Who decides whether to retry, correct, or escalate? An integration without an exception owner is not finished. It has an invisible dependency on whoever happens to notice the problem. In practice, that person is usually the one who is most affected by the data being wrong - which means the exception queue will be discovered in the most stressful possible context rather than through a calm, systematic process.
Failure 3
The integration breaks when either system updates
A field is renamed in the source system during a platform update. A new required field is added to the destination. The API version the integration depends on is deprecated. Any of these changes can break a working integration without anyone building the integration being aware the change is coming.
Fragile integrations are usually built against the current state of both systems without any mechanism for detecting when that state changes. Durable integrations are built with monitoring that alerts when data stops flowing or starts failing validation, and with enough documentation that whoever inherits the integration can understand what it depends on and adjust when those dependencies change.
Failure 4
Bidirectional sync creates conflicts
A contact is updated in the CRM. The same contact is updated in the marketing platform within the same minute. Both updates are valid. The sync runs and the later timestamp wins - but the earlier update contained a change the later update did not include. The result is a record that is partially correct and partially wrong, and nobody knows which parts to trust.
Bidirectional sync requires a conflict policy: which system is authoritative for each field, and what happens when both systems change it before the changes are reconciled? A last-write-wins policy can overwrite an intended value. Check the chosen tool's documented behaviour and configure field ownership or a review route rather than assuming its default matches the workflow.
Choosing the right approach
Choose the connection around the handoff.
Decide when the receiving system needs the change and how it will recover a failed handoff. Then check which approach and provider can support that contract.
Direct API calls
Use an API call when one system needs to request or change data on demand. The caller must handle the response, timeouts and unavailable dependencies.
Before repeating a write, check whether it already succeeded and whether the receiver supports safe repetition. A lost response does not prove that nothing happened.
Webhooks
Use a webhook when a source needs to notify a receiver that an event occurred. Delivery delay, ordering and retry behaviour depend on the provider.
Verify the event, recognise repeated deliveries and retain enough evidence to recover a missed handoff. An unavailable endpoint may cause a retry or a recorded failure, not necessarily a silent loss.
Sync tools
Use a sync tool when its mapping, timing and conflict rules fit the required alignment between systems. Some products poll; others use events.
Check field ownership, supported changes and failure visibility. A managed connection still needs an owner and a reconciliation path; suitability is not determined by whether the data is labelled critical.
The cost of integration debt
What poorly designed integrations cost operationally.
Repair
measure the weekly re-entry, deduplication, and reconciliation work caused by the boundary
Silence
treat unexpected absence of a normal flow as an operational signal
Reconcile
define how a partial or failed write is found, repaired, and proven complete
The design
Most integration failures are design problems, not technical ones
Connection vs integration
Building a connection is technical. Building an integration is operational design that happens to use technical tools.
The difference shows up in how the data behaves under non-standard conditions. A connection handles the happy path: the standard record, the expected field values, the normal sequence of events. An integration handles what happens when a record is incomplete, when a field arrives in an unexpected format, when a step is skipped or reversed, when the business logic on one side changes without the other side being updated.
The design question most teams skip
What should the integration do when the data is wrong?
Every integration will receive bad data eventually. A required field missing. A value outside the expected range. A record that fails validation for reasons nobody anticipated when the integration was built. The question is not whether this will happen. It is whether the integration was designed to handle it.
Work backward from the failure path to find where the data actually went wrong.
When an Integration Breaks, How to Diagnose It ->The cost of finding out late
Answering this during the build is uncomfortable. Answering it under pressure, with production data already wrong, is worse.
This question exposes the cases the initial design did not cover. Handling those cases before launch is usually less disruptive than discovering them through a production failure, when remediation can also leave a data-reconciliation problem behind.
Monitoring output, not just uptime, is how a silent failure surfaces in hours instead of months.
How to Monitor Your Integrations ->Building it
Design starts where the happy path ends
Building integration that holds
Four stages of building an integration that survives real operational conditions.
An integration built in a day can work for months. An integration built carefully can work for years. The difference is not the time spent building - it is whether the design was done before the code was written.
01
Define the data contract first
Before writing a line of integration code, document every field that will pass between systems. For each field: the name in both systems, the data type, the allowed values, what happens when it is missing, and whether it can be null. This document is the integration specification. If two people cannot agree on what goes in it, the integration is not ready to be built. Disagreements about the data contract that surface during this step cost minutes. Disagreements that surface in production cost days.
02
Map the exception cases before the happy path
List every way the integration could receive unexpected data: missing required fields, values outside expected ranges, records arriving out of order, the same record arriving twice, updates to records the receiving system does not have yet. For each exception, decide: reject and log, apply a default value, flag for human review, or retry. This exception map becomes the specification for the integration's error handling. Integrations built without it handle exceptions by accident rather than by design.
03
Build monitoring before you launch
The integration should have monitoring in place before the first production record passes through it. At minimum: a count of records processed, a count of records that failed, and an alert when the failure rate exceeds a threshold. Ideally also: a log of what failed and why, and a way to retry failed records after the underlying problem is fixed. Monitoring built after launch is built after the first production failure has already happened without anyone knowing.
04
Document the dependencies before you hand over
The person who inherits this integration should be able to understand what it does, what it depends on, and what to do when it breaks without asking the person who built it. This documentation does not need to be long. It needs to cover: what data moves between which systems, what the trigger is, what the known failure modes are, who owns the exception queue, and which fields or API versions the integration is sensitive to. An integration without this documentation has an invisible dependency on its original author.
Practical patterns
Four integration design decisions that determine whether the connection holds long term.
The difference between integrations that remain reliable over time and integrations that require constant maintenance usually comes down to a handful of design decisions made early. These are the ones that matter most.
Pattern 1
Prefer one-way data flow where possible
One-way integrations - one system is the source of truth for a given piece of data, and the other system reads from it but never writes back - are simpler to build, easier to debug, and far less likely to produce data conflicts. The temptation to sync in both directions usually comes from wanting to avoid choosing which system is authoritative.
Making that choice explicitly is better than avoiding it. For every data field that flows between systems, there should be a designated source of truth. Other systems can read that data. None of them should write it except through the authoritative system.
Pattern 2
Use identifiers that survive system updates
Integrations break when the identifier used to match records between systems changes. A CRM contact ID that is regenerated when the CRM is migrated. An email address that is updated when a contact changes jobs. A product SKU that is reformatted during a platform upgrade.
Stable integrations are built on stable identifiers: internal IDs assigned at record creation that never change, or external identifiers like domain names that are unlikely to change. Building on mutable identifiers like names or email addresses creates integrations that require manual intervention every time the identifier changes.
Pattern 3
Make the integration observable
An integration that cannot be observed cannot be debugged. When something goes wrong - and something will - the first question is always "what actually happened?" An observable integration can answer that question from its own logs. An unobservable integration requires reconstructing the sequence of events from the records in both systems, which is slow and often incomplete.
Observability does not require elaborate tooling. A structured log that records the timestamp, the record identifier, the action taken, and the outcome is enough to diagnose most integration failures. Build it before launch. Review it after the first month in production.
Pattern 4
Version the integration alongside the systems it connects
When a source or destination system updates, the integration may need to update too. The problem is that system updates happen on the system's schedule, not the integration's. The integration needs to be designed to detect when the systems it connects have changed in ways that affect the data contract.
At minimum, this means documenting which API version or field structure the integration depends on and setting up a way to be notified when those dependencies change. Practically, it means treating the integration as a first-class piece of operational infrastructure - something that requires maintenance - rather than a one-time build. System updates that break integrations are not surprising. They are a known category of event that operational teams should be prepared for, not caught off guard by.
The advanced boundary
A delivery contract needs a recovery model, not just a retry setting.
A retry is a transport decision. Recovery is an operational decision: it defines which event may be repeated, which side effect must happen only once, what evidence proves the destination is correct, and who decides when the automatic path stops.
Write these decisions beside the field mapping. They turn an integration from a sequence of API calls into a recoverable operating system. This is Mannvit's operating recommendation, shaped by documented retry and redelivery behaviour rather than a universal implementation prescription.
Four decisions to document
What a recoverable handoff specifies
Identity: the stable event or operation ID used to recognise a repeat. Do not create a new key for each retry.
Attempt policy: which failures are plausibly transient, how attempts are spaced, and when a retry must stop rather than increase the damage.
Terminal path: where a record goes when it cannot complete automatically, what context accompanies it, and which named owner can resolve it.
Verification: the destination state or reconciliation check that proves a consequential write landed correctly, rather than merely receiving an accepted response.
Stripe doesn't guarantee the delivery of events in the order that they're generated.
This is a Stripe-specific delivery boundary, not a guarantee about every provider. Its documentation also describes duplicate delivery and retries. The receiver must recognise repeats and handle missing prerequisite state rather than relying on arrival order.
Mannvit operating record
Write the handoff down before the first record crosses it.
This is a Mannvit operating recommendation, not a universal vendor specification. The completed example shows the level of decision that needs to exist. The final column is the record to copy into the system documentation.
| Decision | Completed example: CRM to onboarding workspace | Copyable operating record |
|---|---|---|
| Source of truth | The CRM owns the account status. The onboarding workspace may read it but does not write it back. | <name the system and field that own this decision> |
| Trigger and acceptable delay | A status change to `ready_for_onboarding`; the workspace must receive it before the next onboarding task is assigned. | <name the event, required timing, and the decision affected> |
| Field contract | `account_id`, owner, start date, and scope are required. Missing scope is held for review rather than guessed. | <list required fields, allowed values, and missing-value behaviour> |
| Event identity | The CRM change event ID is retained across retries and reconciliation. | <record the stable event or operation ID> |
| Exception owner | The revenue-operations owner receives records that cannot be applied automatically. | <name the person or role that decides the exception> |
| Proof and review | The receiver is read back by `account_id`; the record links to its event and is reviewed when the CRM process changes. | <state how completion is proven and when the record is reviewed> |
The handoff test
A handoff is not complete when it returns success. It is complete when the next system can act safely and another operator can recover it.
In the example above, a duplicate delivery does not create a second onboarding record. A lost acknowledgement does not erase the evidence. A record that cannot be applied leaves a visible decision for the owner instead of becoming a spreadsheet repair later.
The technical teardown of a repeated delivery, a lost acknowledgement, and a safe receiver.
See the duplicate-delivery case in detail ->receive event
validate required fields
if event ID is already complete:
return the recorded result
if the destination cannot accept the record safely:
preserve the event and route it to the named exception owner
do not guess a value or mark the handoff complete
apply the change once
read back the consequential destination state
record the event ID, result, and evidence of completionThe vendor-neutral rule: preserve identity, stop unsafe work, then verify the state that the next operator will rely on.
async function applyOnboardingHandoff(event) {
assertRequired(event, ['eventId', 'accountId', 'owner', 'startDate']);
const prior = await handoffLog.find(event.eventId);
if (prior?.status === 'complete') return prior.result; // repeated delivery
if (!event.scope) {
return exceptionQueue.add({ event, reason: 'Missing onboarding scope' });
}
const result = await onboardingWorkspace.upsert(event.accountId, event);
const saved = await onboardingWorkspace.get(event.accountId); // consequential read-back
if (!matchesExpected(saved, event)) throw new Error('Destination state needs reconciliation');
await handoffLog.complete(event.eventId, { accountId: event.accountId, result });
return result;
}Illustrative JavaScript, not drop-in production code. The durable boundary is the stable event ID, explicit exception queue, and verified destination state.
Test the failure paths you can identify
Missing required fields, changed identifiers and duplicate deliveries are useful pre-launch test cases. Test the receiver's response and recovery route for each. These checks reduce avoidable surprises; they do not predict every production failure.
Fragile integrations are usually an ownership problem, not a technical one
The most common cause of an integration becoming fragile over time is not technical debt. It is that nobody reviewed it when the upstream system changed, nobody investigated when exceptions started accumulating, and nobody felt responsible for what it does after it was launched.
The cost of a bad integration is in the downstream data
A broken integration does not always announce itself. It keeps running, but with wrong data. Every record it processes after the failure compounds the cleanup cost. By the time the problem is visible in a report or a decision, the remediation is already expensive, not because the integration is complex, but because the error has been accumulating for weeks.
Monitoring is cheaper than debugging after an outage
Record the operation identifier, affected records and documented result while the integration runs. Reconstructing that evidence after a failure can be difficult when the two systems retain different histories. Keep enough evidence to distinguish a failed operation from an uncertain outcome before deciding to replay it.
Owning it
Integrations that hold are treated as infrastructure
The long view
Integrations that hold are treated as infrastructure, not as features.
The hardest thing about integrations is not building them. It is maintaining them as the systems they connect evolve. A well-built integration from two years ago can become a fragile one if neither system nor the business processes they support have stayed the same.
Teams that have reliable integrations over the long term treat them the same way they treat other operational infrastructure: with designated ownership, regular review, and a clear process for handling the changes that will inevitably arrive.
Without review or monitoring, an upstream change can leave the receiver using incomplete or incorrect data until somebody notices the downstream result. Assign an owner to review changes and investigate failures. Set the review frequency according to the connection's risk and rate of change, rather than assuming a quarterly review suits every integration.
A failure can leave manual workarounds, uncertain reconciliation and documentation that no longer matches the connection. Review those costs alongside monitoring and maintenance effort. Whether preventive work saves money depends on the failure frequency, consequences and cost of the proposed controls; this guide does not claim a measured saving.
Designate an owner
Every integration needs someone whose job includes noticing when it stops working and caring enough to fix it. Not a technical owner - an operational owner whose workflow depends on the data being correct.
Review quarterly
Check the failure rate, review the exception queue, confirm the data contract still matches how both systems are actually used. Thirty minutes quarterly prevents most of the slow drifts that turn a reliable integration into a brittle one.
Document before it breaks
The integration documentation that matters most is the kind written before anyone needs it: what it does, what it depends on, what to do when it fails. Documentation written during an outage is documentation written under pressure.
Common questions
Questions about system integrations
Fragile integrations are built on mutable identifiers, have no data contract, route failures silently, and have no named owner after launch. Reliable integrations are the opposite: they use stable identifiers, have an agreed data contract, surface failures visibly, and have someone who reviews them when the systems they connect change. The technical complexity is often similar. The design decisions around ownership and failure handling are what determine how long the integration holds.
No-code tools are a good fit when the data contract is simple, the transformation logic is minimal, and the volume is low enough that a queue of failures is manageable by hand. Custom integrations make more sense when the transformation logic is complex, the exception handling needs to be precise, or the integration carries enough operational weight that a queue of unhandled failures would cause real damage. The decision should be made on those criteria, not on cost or speed, a cheap integration that produces bad data is expensive.
Build monitoring that checks output, not just operation. An integration can run without errors and still produce wrong data, if an upstream field is renamed, if a filter condition no longer matches, if a transformation produces empty results instead of failing. Monitoring that checks the volume and quality of what the integration produces, not just whether it ran, will catch silent failures before they compound into a data cleanup project.
A data contract is an explicit agreement between two systems about what data will be sent, in what format, with what guarantees, and what should happen when those guarantees are not met. Without one, each side can change independently and break the other without knowing it. With one, changes require coordination and the integration can verify at runtime that the contract is still being met.
If your systems are connected but the data between them still requires manual cleanup, the integration design needs reviewing.
Bring one record that needed manual cleanup, its source evidence, and the expected destination state. Trace where they diverge before deciding whether the repair belongs in the mapping, exception path, ownership rule or monitoring. Some failures need a deeper technical investigation; this gives that investigation a concrete starting point.
Bring the page, report, or workflow as it is now.
We reply with the clearest next step, or an honest no.
