An API connection needs an operational contract
An integration connects two systems with different data models, permissions and failure modes. “There is an API” is the start of discovery, not proof that the required workflow is available.
Identify the authoritative system for each object and the direction of synchronisation. Define identifiers, allowed changes, expected delay and conflict behaviour. Avoid two systems overwriting each other without an ownership rule.
Investigate before estimating the full build
| Question | Evidence |
|---|---|
| Can the API perform the required action? | Current documentation and a permitted test |
| Which identity performs it? | Scoped credentials and server-side storage |
| How are changes discovered? | Verified webhook or documented polling model |
| What happens on retry? | Stable operation identifiers and duplicate handling |
| What happens during an outage? | Queue, retry policy and visible failure state |
| How is success reconciled? | Stored remote identifiers and comparison report |
Do not place privileged credentials in public build variables or browser requests. Keep secrets server-side and restrict access to the operations the integration needs.
Assume events can repeat or arrive unexpectedly
Webhook behaviour varies by provider. Verify signatures or the documented authentication mechanism before accepting an event. Persist a provider event identifier when available and make repeated processing safe. Do not assume that arrival order always matches business order.
Stripe’s webhook documentation describes its own verification and delivery behaviour; another provider may use different guarantees. Read the actual provider contract rather than copying settings blindly.
Test reconciliation and recovery
Try a duplicate event, a timeout after a successful remote operation, an invalid signature and an unavailable destination. Confirm that retries do not create a second customer, payment request or task.
Release with monitoring and an operator procedure for failed jobs. A working demo request is useful evidence, but a dependable API integration also needs recovery, revocation and data ownership rules.
A practical question
What should happen after an ambiguous API timeout?
Reconcile using a stable operation identifier before repeating a consequential action. A timeout describes the missing response; it does not prove the destination failed to apply the operation.