API integration checklist: beyond the happy path.
A reliable integration defines the source of truth, validates access and data, handles retries without duplicating work and exposes failures to an operator. A successful test request proves only one part of the flow.
Use the free worksheetTest what happens after the first success.
Illustrative example: an external order event should create one fulfilment task. The task must still be correct when events repeat or a dependency fails. These are proposed acceptance checks, not delivery guarantees shared by every API provider.

| Test input | Required business result | Evidence to inspect |
|---|---|---|
| Same event, twice | One fulfilment task for the same business operation. | Match the operation identifier to one resulting task. |
| Same event, concurrently | Concurrent workers must not both create the task. | Exercise the overlap. A sequential duplicate test is insufficient. |
| Older event arrives last | An older event must not overwrite a newer authoritative state. | Compare the stored state with the provider's ordering or version contract. |
| Timeout after remote success | Reconcile the completed operation before attempting to create it again. | Look up the operation using the agreed stable identifier. |
| Access expires | Expose a recoverable failure to the operator. | Renew access in the test environment and verify controlled replay. |
Run it: two event IDs, one order.
Our downloadable JavaScript example uses fictional orders to isolate a common mistake: treating the event ID as the identity of the work. It receives one event twice, then a second event for the same order. All three deliveries must leave one fulfilment task. Changed item counts are rejected for review; a different order or shop creates a separate task.
Download the file, inspect it and run it with Node.js. It uses only built-in modules, makes no network requests and writes no files. Assertions stop execution if an expected result changes. The final check creates a new ledger to show that memory alone forgets previous work.
This is a single-process teaching model, not a webhook receiver. It assumes one fulfilment task per shop and order. Production needs signature verification, durable atomic storage, worker coordination and a recovery strategy for external side effects. Partial shipments need a different business key. Passing this example does not test those requirements.
Run locally after downloading. Expected output:
node webhook-replay.mjs
3 deliveries, 2 event IDs, 1 fulfilment task
Conflicting item count: rejected, still 1 task
Incomplete or invalid input: rejected, still 1 task
Different order or shop: separate tasks, 3 in total
New ledger: previous work is forgotten (memory-only limit)Choose who owns each piece of data.
If a customer changes an address in two systems, which value wins? If an order is deleted, should the integration delete the corresponding record elsewhere? These are product decisions, not details to leave to the connector.
Map the fields and the direction of updates. Record identifiers used to match records across systems. A display name or email address may change, so it is not automatically a suitable permanent identifier.
Check access before promising the integration.
Read the documentation for the actual provider, plan and API version. Confirm the operations available, authentication method, account permissions and test environment. An API existing does not mean the required account can use every endpoint.
Credentials should have the access the integration needs and a documented renewal path. Store them outside the source repository. Define what an operator sees if credentials expire or access is revoked.
Assume an event may arrive again.
Providers can retry event delivery. Stripe's webhook documentation, for example, describes retries, duplicate events and a lack of guaranteed event ordering. Check your provider's contract rather than assuming every event arrives once and in sequence.
Make the business operation safe to retry. Track the provider's event or operation identifier and the result already produced. If an earlier attempt timed out, inspect what happened before issuing the same action again.
An outbound request is a separate boundary. Stripe's API v1 supports idempotency keys for POST requests: reusing a key with the same parameters lets a retry return the saved result, within the provider's retention rules. That does not replace your incoming event ledger or make a second system's side effects atomic.
Distinguish temporary failure from invalid work.
A temporary service outage may justify a later attempt. A malformed address or revoked permission usually needs a different response. Repeating every failed request indefinitely can make a bad state harder to recover.
Define timeouts, provider limits and the point where an operator takes over. Keep diagnostic information useful enough to resolve the issue, while avoiding credentials and unnecessary personal data in logs.
Test the operational result.
Use representative scenarios: duplicate delivery, a late event, a provider outage and a manual change in the destination system. Check the resulting records, not just the HTTP status returned by the connector.
For an order integration, a useful acceptance test might show that replaying the same paid event leaves one order and one fulfilment request. Then rehearse how a failed event is inspected and retried. That turns recovery into a supported workflow.
The checklist.
- Source of truth and field mapping agreed.
- Actual account access and API version checked.
- Duplicate and out-of-order events considered.
- Retries cannot casually repeat the business action.
- Provider limits and credential renewal documented.
- An operator can inspect and recover failed work.
Take it into the project.
API integration test worksheet.
Map a business operation across systems, then write the tests for duplicates, ordering, failures and recovery.
Download the worksheet (.txt)Plain text, ready to edit. No account or email required.
Preview the worksheet questions
- Business operation
- Describe the trigger, systems involved and completed result. Name the operator who owns the flow.
- Source of truth
- For each field, record authoritative system, stable identifier, update direction and deletion behaviour.
- Provider contract
- Record provider, API version, account plan, permissions, limits, event guarantees and test environment. Link to the documentation checked.
- Authentication and renewal
- Record the credential owner, required scopes, renewal process and expected behaviour after expiry. Do not include credentials.
- Duplicate and ordering tests
- Deliver an event twice, deliver duplicates concurrently and deliver events in reverse order. State the expected business state after each.
- Ambiguous timeout test
- Simulate an external operation completing before your client times out. How will the system reconcile it without creating duplicate work?
- Failure and replay
- Define retry limits, invalid records, failure visibility and a controlled replay process. State the evidence that replay is safe.
- Release evidence
- Record environment, operation IDs, observed outcomes, unresolved cases and the person accepting the integration.
Sources.
Technical references checked on .