An integration rarely becomes unmanageable in one dramatic moment. The warning signs accumulate: a scheduled job needs another manual restart, one person learns a new exception, a reconciliation is postponed, and nobody is quite sure whether a green dashboard represents complete data.

Often, the missing piece is a shared understanding of what the integration should do, how to check it and who responds when it fails. That can be put right.

These seven signals are useful prompts for a health check.

1. Success means “the job finished”

A scheduler can report success after moving an incomplete dataset. An API can return a successful status while individual records are rejected. A file can arrive with the right name and the wrong accounting period.

Technical completion is one piece of evidence. Operational success also needs business-level checks: expected record counts, totals, freshness, duplicates and referential rules. The checks should reflect the process. An order integration might compare source and target counts by state; a finance pipeline might reconcile transaction value by subsidiary and period.

Agree the checks that show the business process succeeded, then make them visible alongside the job status.

2. Failures depend on somebody noticing

An unread inbox, a red icon on a dashboard or a log entry is not an alerting system. A useful alert reaches an owned route, contains safe diagnostic context, and distinguishes action from noise.

Define the conditions that require a response. Include missed schedules, exhausted retries, reconciliation failures, unexpected volume changes, authentication expiry and growing queues. Each alert should name a run or request identifier, the affected interface and the safe next step. It should not include customer, employee or financial content.

If the same warning is routinely ignored, either the threshold is wrong or the underlying condition is being normalised. Both deserve correction.

3. Only one person knows how it works

The issue is not that one specialist knows the most. It is that essential recovery knowledge exists only in memory: which credential expires, which query must be restarted, which records are safe to replay, and which team must approve a correction.

Minimum operational documentation should cover:

  • purpose, source, destination and data owner;
  • schedule or trigger and expected latency;
  • authentication and secret-rotation owner;
  • field mapping and transformation rules;
  • monitoring, reconciliation and alert routes;
  • replay boundaries and idempotency assumptions;
  • known failure modes and escalation path.

Test the document by asking a second operator to diagnose a controlled failure. A runbook that has never been used is still a hypothesis.

4. Every replay risks duplicates

Transient failures are normal in distributed systems. If retrying a message or batch can create a duplicate order, customer or transaction, routine recovery becomes a high-risk manual decision.

Use stable source identifiers and idempotency keys. The HTTP semantics standard defines the intended effect of repeated idempotent requests, while AWS’s reliability guidance for mutating operations describes using a repeated token to prevent duplicate side effects. Separate the receipt of work from its side effects where appropriate. Record durable checkpoints only after the corresponding data is safe. For batch pipelines, use bounded extraction windows and merge semantics that allow the same window to be processed again.

The desired property is simple to state: repeating the same accepted input should not create a second business effect. Achieving it may require support from both systems, but the constraint needs to be explicit.

5. Changes arrive as surprises

Fields are renamed, pick-list values expand, permissions change, APIs are deprecated, and administrators customise source systems. An integration becomes brittle when these changes are first discovered by a production failure or—worse—by a user who notices wrong data.

Keep versioned schemas and mappings. Validate required fields at the boundary. Capture unknown optional fields without silently treating them as trusted. Monitor vendor change notices and certificate or token expiry. Introduce contract tests for interfaces under your control, and schedule a review for account-specific systems such as NetSuite, Salesforce and Jira.

Change control should be proportionate. The goal is not to freeze every source system; it is to make the downstream consequences visible before deployment.

6. Logs contain either nothing useful or far too much

At one extreme, operators see “failed” with no request identifier or stage. At the other, logs contain full request bodies, email addresses and business records. Neither is operable.

Use structured, minimal telemetry. Useful fields include integration name, environment, run or request identifier, stage, safe error category, attempt count, record count and duration. OpenTelemetry’s stable logs data model provides standard concepts such as timestamps, trace identifiers, severity and attributes without prescribing that the business payload itself be logged. Keep sensitive business content out. Control access and retention according to the data classification.

Metrics should answer a small set of recurring questions: Is the integration running? Is it keeping up? Is the data complete? Are failures increasing? How long does recovery take? Logs then provide the specific evidence for an incident.

7. Ownership ends at deployment

An integration crosses organisational boundaries. The source team may own field meaning, the platform team may own runtime health, and the receiving business team may own acceptance. Problems persist when those responsibilities are assumed rather than agreed.

Name an accountable owner for the interface and contributing owners for source data, destination behaviour and infrastructure. Define support hours and severity. Establish who can approve a replay, correct source data or change a mapping. Include ongoing cost and vendor-limit review.

Delivery is not complete until the support route, evidence and authority to recover are in place.

A focused health-check sequence

You do not need a transformation programme to assess the risk. Start with one business-critical flow and follow it end to end:

  1. identify the business event and expected outcome;
  2. trace the data across every queue, file, API and transformation;
  3. inspect a normal run and the last three meaningful failures;
  4. compare technical checks with business reconciliation;
  5. attempt a safe replay in a non-production environment;
  6. map owners, access, documentation and escalation;
  7. rank gaps by business impact and likelihood.

The output should distinguish containment from structural improvement. Adding an alert may reduce detection time now; redesigning an unsafe replay path may take longer. Both can be planned without hiding the trade-off.

The standard to aim for

Aim for an integration where your team can spot a failure, understand its impact and recover safely. Check data completeness, review changes and share the knowledge needed to keep it running when someone is away.

You can check these qualities whatever technology you use. If several warning signs sound familiar, start by mapping how the integration works today. You’ll have a clearer basis for deciding what needs a small repair, what needs rethinking and what already works well.