Reliable API integrations: the business checklist beyond ‘it connects’

Define what ‘working’ means in business terms

An integration can return a successful HTTP response while the business process remains incomplete. A customer record may exist in the CRM, for example, while the finance system rejected the billing address. Define success as a verifiable outcome across the participating systems, not simply a successful connection.

Start with a short contract: when a specified event occurs, which records must exist, which fields must agree, how quickly should they converge, and who resolves exceptions? Include the customer or employee experience when the process is delayed. A user should not have to submit the same request repeatedly because the interface provides no useful status.

1. Assign a source of truth to each field

Map identifiers and field ownership before writing transformation logic. The CRM might own a sales contact’s communication preference while the billing platform owns payment status. Avoid a general rule that whichever system updates last is always right; that can overwrite a valid business decision with an older event.

Document how records are matched, how updates are versioned and how deletions or merges propagate. Consider a customer changing an email address while an invoice is being created. If email is used as the only identity key, the systems may create duplicate customers. Prefer stable identifiers where the connected products support them, and test the behaviour when a match is uncertain.

2. Expect duplicates and out-of-order delivery

Stripe’s webhook documentation explicitly warns that event delivery order is not guaranteed and that duplicate events can occur. It also describes signature verification and recommends prompt successful responses before complex processing. These are documented behaviours of Stripe; check the equivalent contract for every provider you integrate. [1]

As an implementation pattern, record an incoming event durably, associate it with a stable identifier and prevent concurrent workers from applying the same business operation twice. A database uniqueness constraint can be part of that protection. Do not acknowledge successful acceptance before the event is safely captured, or a process crash could lose the work.

Distinguish the event from the underlying action. Two different notifications might refer to the same invoice state, while a retry might reuse the same event identifier. Define duplicate handling around the business effect and the provider’s semantics, then test both cases.

3. Make access control a server-side responsibility

The OWASP API Security Top 10 highlights risks including broken object-level authorisation, broken authentication, unrestricted resource consumption and unsafe consumption of third-party APIs. It is an awareness resource, not a complete test plan for a particular application. [2] Use it to challenge the assumptions in your integration design.

Check whether a user can request another customer’s record by changing an identifier. Verify permissions inside the service handling the request, not only in a hidden button or browser screen. Give each integration only the permissions it needs, store credentials outside application source, and define how revoked access is detected and handled.

For inbound events, verify authenticity using the provider’s documented mechanism. Validate the payload and impose appropriate request and processing limits. An integration should not treat third-party data as automatically trustworthy merely because it arrived from a familiar product.

4. Plan retries and reconciliation together

Classify failures into those that may succeed later and those requiring correction. A temporary timeout is different from a rejected field value. Use bounded retries with increasing delays where appropriate, then send unresolved work to an exception queue with an owner. Endless silent retries can obscure a persistent business problem.

Add reconciliation: periodically compare the important business state across systems and surface differences. For example, identify orders marked paid by the payment system but still waiting for fulfilment internally. Design the repair action to be repeatable and auditable. Replaying a message should not create another shipment or another invoice.

5. Test failure paths before launch

Prepare acceptance scenarios with the business team. Include a normal transaction, a duplicate event, delayed delivery, a malformed record, expired credentials, a disconnected destination and a process restart after partial completion. Observe the final state in every system, not just the integration logs.

For a hypothetical order workflow, intentionally stop processing after payment is recorded but before the fulfilment task is created. Restore service and verify that the missing task appears once, with the original order identifier and a traceable history. This exercise can reveal more about operational reliability than repeatedly testing successful orders.

6. Give operations useful visibility

Track processing delay, error categories, unresolved exceptions and reconciliation differences. Attach a correlation identifier to the business transaction so support staff can trace it without copying sensitive payloads into tickets. Keep logs purposeful, restrict access and define retention based on actual operational and compliance needs.

Before handover, agree who owns alerts, provider API changes, credential rotation and repair decisions. Write a runbook that a colleague can follow when the original developer is unavailable. Evo’s Software Development service covers APIs, internal tools and workflow automation; an integration assessment can turn a fragile connection into a documented, testable business process. Managed IT support can then help sustain its daily operation.

Frequently asked questions