Define the business event
Start with what has happened in the business, not with the API endpoint. An invoice being created is different from an invoice being approved or paid. Define when the event is valid, which system owns the record and what the receiver is allowed to change. Include how corrections and cancellations are represented.
Design for duplicate and delayed delivery
Networks fail and callers retry. Give each business operation a stable identifier and determine how the receiving system recognizes a repeat. Decide which operations can be applied safely more than once. For ordered workflows, explain what happens if an update arrives before its prerequisite; do not assume delivery order will always match creation order.
Make failures actionable
Separate temporary failures from invalid data and permission errors. Define retry limits, an exception queue and the person responsible for resolving it. Preserve enough context to diagnose the failure without putting secrets or unnecessary personal information in logs. An alert that merely says integration failed creates investigation work rather than guiding recovery.
Reconcile business state
Successful API responses do not guarantee that two systems remain consistent. Plan a periodic comparison of important records or totals and a process for handling differences. Specify how deleted records, changed identifiers and partially completed operations are treated. A reconciliation procedure is especially useful when a vendor does not provide reliable event history.
Review changes and access
Use dedicated credentials with the smallest useful permissions, assign an owner and plan rotation. Document rate limits, version changes and support contacts. Test using representative payloads before deployment and retain a safe way to disable the integration. The delivery checklist should include recovery instructions and a demonstration of one failed operation being diagnosed and replayed safely.
Rehearse an integration failure
Suppose a payment event arrives twice while the receiving system is unavailable. Decide how the event is stored, retried and recognised when it arrives again. Then test how an operator can find the affected transaction without searching several unrelated logs.
- Use a stable business identifier for reconciliation.
- Bound retries and isolate repeatedly failing messages.
- Make duplicate processing safe for the business action.
- Document the procedure for replaying a failed event.
Transport success does not prove business completion. A receiving API can accept a request while a later step fails. Provide a way to compare the final business state across systems and resolve differences deliberately.
Start with what has happened in the business, not with the API endpoint. An invoice being created is different from an invoice being approved or paid.