Agree on an integration contract
Document field meanings, identifiers, required values and ownership. Define success and what happens if the receiving system is unavailable. Include version changes and access rules. A shared customer name is not a reliable unique identifier; use a stable key and explicit mapping between the records in each system.
Make retries safe for each operation
A request may succeed remotely while its response is lost. Blindly retrying creation can duplicate a payment or order. Use supported idempotency mechanisms or a deliberate deduplication design. Idempotency describes the intended effect of repeated requests; it does not require every response to have identical content or the same status code.
Verify events and expect delays
Authenticate notifications using the provider’s documented method. Track event identifiers and handle repeats or out-of-order delivery. Set timeouts and bounded retries with backoff. Move unresolved events to a visible review queue. A temporary error should not automatically trigger repeated irreversible actions or create an invisible backlog of failed work.
Build reconciliation and support tools
Keep correlation identifiers so transactions can be traced without logging secrets. Compare source and destination records on an agreed schedule. Give support a controlled way to inspect failures and record resolutions. Test disconnection, duplicate events and destination outages before declaring an integration complete; success-path demonstrations cover only part of the job.
Example: a payment notification delivered twice
Suppose a payment provider sends a successful-payment event and later retries the same event because it did not receive acknowledgement. The receiving system should recognise the event and avoid creating a second business effect.
Store a suitable event reference and apply the provider’s verification rules. Test what happens when the notification arrives before the browser returns, after a timeout or out of order with another event. This is an illustrative integration scenario.
Prepare an integration contract and a failure queue
- Stable record identifiers and field ownership.
- Authentication, event verification and allowed operations.
- Timeout, retry and deduplication rules.
- A visible queue for unresolved events.
- Reconciliation reports and a support owner.
Define which failures can be retried automatically and which need review. Financial or irreversible operations should not be repeated just because a generic retry mechanism is available.
Make the handover understandable to support
A support operator should be able to locate a transaction, see its last confirmed state and identify the next responsible team without viewing secrets. Include a documented escalation path and an audit trail for manual resolution.
During acceptance, simulate a temporary outage and recover the pending work. An integration is operationally incomplete if only its developer can tell whether a failed request has already succeeded elsewhere.
