Systems & integration
An integration is an operating agreement
An endpoint connects two applications. A dependable integration also explains what the exchange means, who owns its state and how people recover when the expected response never arrives.
Imagine a hypothetical order moving from a sales platform to a fulfilment service. The request leaves the sales platform, but the response is lost. The support team sees a pending order. The warehouse may already be preparing it. Should the request be sent again, and what would make that second attempt safe?
This is a useful starting point for an integration review. AWS explains that a timeout or failure does not necessarily mean a remote operation had no side effects. Retrying can also increase pressure on a service that is already struggling. [1] An operating agreement makes those uncertain situations explicit before they become somebody's support problem.
Agree on the meaning of the exchange
Start with a small set of business statements. What does accepted mean? When can the order change? Which application owns its current status? Who can cancel it after fulfilment has started? Put those statements beside the technical contract so a field name does not have to carry the whole explanation.
A useful contract identifies required information, permissions, validation rules, possible responses and compatibility expectations. Add examples of incomplete and contradictory information. In the order scenario, distinguish a request rejected before acceptance from one accepted for later processing. The interface and the support procedure should describe those outcomes consistently.
Choose an owner for each definition. A data mapping document becomes much more useful when the people maintaining the source and destination agree on what the mapped value means and which side can change it.
Keep the identity of an attempt separate from the work
For an operation with side effects, define a stable identity for the intended business action. A retry of that action should be recognisable as a repeat. Creating a fresh identifier for every network attempt would defeat that particular form of duplicate protection.
Stripe's API provides an idempotency-key mechanism for safely repeating eligible requests. Its current documentation distinguishes API v1 and v2 behaviour, including how completed and failed work is treated. [2] That specificity matters: check the API version and the provider's contract instead of assuming every service uses the same response-caching rules.
For an internal integration, document the identity's scope, how long duplicate protection lasts and what happens if the same identity arrives with different information. Decide how an operator can distinguish a deliberate new action from a retry. Those decisions belong in the implementation and the runbook.
Give uncertainty a time budget
A recovery policy needs a limit. Specify which failures are eligible for another attempt, how long the overall action can remain pending and who takes responsibility after that budget is exhausted. Make the customer-facing status and the operational status fit the same lifecycle.
AWS describes backoff as increasing the interval between retries and jitter as varying their timing to avoid synchronised bursts. It also cautions that retries can amplify load. [1] Choose the retry policy at the appropriate boundary and review what the libraries, gateways and workers already do. Several independently reasonable policies can be difficult to understand when combined.
In the hypothetical fulfilment exchange, exhausted retries might place an order in a review queue with its history preserved. The important next step is a defined investigation or reconciliation action, with enough information to avoid guessing whether the order should be sent again.
Expect events to need interpretation
An event-driven interface needs its own delivery assumptions. Stripe documents that webhook events can be delivered more than once and are not guaranteed to arrive in generation order. Its guidance includes recording processed event identifiers and retrieving missing objects when necessary. [3] A consumer should follow its actual provider's documented guarantees.
For the order flow, specify how a repeated status update is recognised and how an older update is prevented from undoing a later business state. Keep receipt of the message distinct from successful completion of the business action. Decide what evidence is retained when validation fails and how an authorised operator can replay or reconcile the work.
Design the support conversation
Before release, rehearse one missing response, one duplicate delivery and one prolonged outage. Ask someone responsible for operating the integration to explain where they would look, what they can safely do and when they need help from the other system's owner.
The handover should include the contract, ownership contacts, useful identifiers, monitoring expectations and a recovery procedure. Keep sensitive payloads out of casual diagnostic views; decide what information is necessary for investigation and how access is controlled. An integration is ready to operate when its uncertain states have a clear vocabulary and a responsible next action.
Sources & further reading
The references behind this perspective. Reviewed . Product documentation can change; check the source before making an implementation decision.
- AWS Builders' Library — Timeouts, retries, and backoff with jitter
Primary engineering guidance for uncertain side effects, retry amplification, timeouts, backoff and jitter; checked 21 October 2026.
- Stripe API reference — Idempotent requests
Current primary reference, including the documented distinction between API v1 and v2 idempotency behaviour; checked 21 October 2026.
- Stripe — Receive events in your webhook endpoint
Primary guidance on duplicate webhook deliveries, event ordering and retrieving related objects; checked 21 October 2026.
