An API integration is not complete when one successful request appears in a development console. A production workflow also needs clear ownership, valid data, secure credentials, predictable failure handling, useful logs, and a plan for change.
Planning these details before implementation reduces expensive surprises. The checklist below can be used during discovery, technical design, provider review, and handover.
1. Define the business event and outcome
Write the workflow in plain language before discussing endpoints. For example: “When a valid website enquiry is accepted, create or update the contact in the CRM, attach the original source, and alert the assigned owner.”
Identify:
- what starts the workflow;
- what a successful outcome looks like;
- which system is the source of truth;
- who owns the process when automation stops;
- which steps are essential and which can happen later;
- what must never happen twice.
This prevents the integration from becoming a collection of disconnected API calls.
2. Map every participating system
List the application, provider, environment, account owner, documentation, and access contact for each system. Note whether a sandbox exists and whether its behaviour differs from production.
Clarify boundaries. A website may collect the information, an API route may validate it, a CRM may own the customer record, and a messaging provider may deliver a notification. Each boundary creates a place where permissions, formats, or availability can fail.
If the workflow connects to a sales process, review the intended pipeline and ownership rules alongside the CRM setup service, rather than treating the API and CRM as unrelated projects.
3. Document the data contract
For every field, record its name, type, required status, allowed values, maximum length, and meaning. Include example payloads that contain realistic edge cases without using real personal data. The browser-only JSON formatter can help you inspect a safe example payload; it validates syntax rather than an API schema.
Decide how to handle:
- missing and blank values;
- dates, times, time zones, and currencies;
- phone numbers and country codes;
- identifiers generated by different systems;
- enumerations whose labels do not match;
- deleted, merged, or archived records;
- schema versions and newly introduced fields.
Validation should happen at the boundary, not only in the user interface. Client-side validation helps people correct mistakes; server-side validation protects the system.
4. Choose authentication and credential ownership
Confirm whether the provider uses API keys, OAuth, signed requests, mutual TLS, or another method. Record the scopes required and avoid granting broader access for convenience.
Credentials should remain on the server, outside source control and browser bundles. Define who can create, rotate, and revoke them; which environments use separate credentials; and how expiry or revocation will be detected.
If you need to inspect a non-secret encoding example, the browser-only Base64 converter can help. Base64 is encoding, not encryption: never paste a live credential or token into an online tool.
For OAuth, include consent, token refresh, account disconnection, and re-authorisation paths. A refresh token is not a permanent guarantee of access.
5. Design idempotency and duplicate handling
Networks retry. Users double-click. Providers may send the same webhook more than once. The workflow needs a stable way to recognise an operation it has already processed.
Depending on the provider, that may use an idempotency key, an event ID, an internal operation record, or a unique database constraint. Specify how long duplicate identifiers are retained and what response a repeated request receives.
“Check and then insert” is not enough under concurrency unless the database or provider also enforces uniqueness.
6. Plan timeouts, retries, and queues
Every external request needs a finite timeout. Decide which failures are safe to retry and use bounded retries with increasing delay and jitter. Do not retry invalid credentials or malformed payloads as though they were temporary outages.
Ask whether the user must wait for the provider. Often the primary action can be accepted durably, then processed by a queue. If asynchronous processing is used, define the visible status, retry policy, dead-letter handling, and manual recovery path.
7. Treat webhooks as untrusted input
For incoming webhooks:
- verify the provider signature using the raw request body when required;
- enforce content type and payload-size limits;
- validate timestamps or replay windows;
- store or recognise the event ID before performing side effects;
- acknowledge within the provider’s timeout;
- process long-running work asynchronously;
- revalidate any URL supplied in an event before fetching it.
Do not assume an obscure webhook URL is secret. Log verification failures without recording credentials or unnecessary personal data.
8. Make failure observable
“The API returned an error” is rarely enough to resolve an incident. Define structured logs and operational signals that answer:
- which workflow and environment failed;
- which internal operation or provider event was involved;
- whether the failure is transient or permanent;
- how many attempts occurred;
- whether data was partially written;
- what the operator should do next.
Use correlation identifiers across systems. Redact tokens, passwords, payment details, and sensitive personal fields. Agree on alert thresholds so a single recoverable error does not create noise while a sustained outage is not missed.
9. Review privacy and security
Minimise the fields sent to each provider. Document the purpose, lawful basis where applicable, processor relationship, data location, retention, deletion process, and access controls. Make sure public-facing privacy information matches the implemented flow.
If the integration accepts a user-provided URL, defend against access to loopback, local, link-local, and private network addresses. Revalidate redirects and limit response size and download time.
Security review should also cover rate limits, abuse controls, origin expectations, audit logs, and the provider’s incident and deprecation process.
10. Test the failure paths
A useful test plan covers more than a successful request. Include:
- missing and malformed fields;
- expired or revoked credentials;
- permission errors;
- rate limiting;
- provider timeout and outage;
- duplicated requests and webhook events;
- out-of-order events;
- unexpected enum or schema values;
- partial success across several systems;
- retry exhaustion and manual replay;
- rollback or compensation where an action cannot simply be reversed.
Use sandbox accounts and safe test data. Do not send real customer messages, payments, or enquiries merely to demonstrate the interface.
11. Plan rollout and rollback
Decide how the integration will be enabled, monitored, and disabled. A feature flag, limited pilot, shadow write, or staged account rollout may reduce risk. Record the old workflow that remains available during transition and the conditions that trigger rollback.
Before launch, confirm production credentials, provider approval, DNS or callback URLs, rate limits, budgets, monitoring, and on-call ownership.
12. Make handover part of the deliverable
Handover should identify the system owner, code location, environment variables, provider account, data mappings, diagrams, known limitations, recurring charges, dashboards, alert routes, recovery steps, and maintenance expectations.
Record provider API versions and deprecation notices. Agree on who reviews breaking changes and whether ongoing maintenance is included or separately scoped.
A concise integration brief
Before implementation begins, the team should be able to answer:
- What business event starts this flow?
- Which system owns each record and identifier?
- What data crosses each boundary?
- How is access authenticated and rotated?
- How are duplicates prevented?
- Which failures are retried, queued, or escalated?
- How are webhooks verified?
- What is logged, alerted, and redacted?
- How will privacy, cost, and provider limits be managed?
- How will the integration be tested, released, recovered, and maintained?
Explore API integration for related scope considerations, read how to write a website brief for the wider project context, or share the systems and workflow you need to connect. If AI is one part of the workflow, review the provider, data, evaluation, and human-review questions on the AI integration page as separate design decisions.