Playbook
API Integration Checklist
Use this checklist before connecting your product to a third-party API. It covers the failures that appear in production: timeouts, duplicates, rate limits and lost webhooks.
Best reader
Engineering leads and product owners planning integrations with payment, CRM, ERP, messaging or AI providers
Outcome
An integration that fails safely, can be monitored and can be changed without surprises.
Use this sequence
Read the provider documentation for limits, authentication, versioning and error formats.
Design authentication and secret storage, one credential per integration.
Make every write idempotent and every retry bounded.
Handle rate limits with queuing and backoff.
Verify, deduplicate and replay webhooks.
Test failure modes, then monitor and alert in production.
Plan for failure first
The happy path rarely breaks. Timeouts, duplicates and partial failures do.
Timeouts on every call
Idempotency keys on writes
Bounded retries with backoff
A dead-letter path for what cannot be processed
Treat webhooks as untrusted and unordered
Webhooks can arrive twice, late or out of order. Verify them and process them safely.
Check the signature
Acknowledge fast, process later
Deduplicate by event ID
Store the raw payload for replay
Own the contract
Providers change. Pin versions where you can and keep a record of what you depend on.
API version pinned
Fields you rely on listed
Change notices routed to a named person
Start in 60 seconds
Turn this checklist into a scoped plan.
Answer a few questions and get an AI-assisted, architect-reviewed scope, cost range, and timeline for your software project.
Frequently asked questions
What is an idempotency key?
A unique value sent with a write request so the provider can recognize a repeat and return the original result instead of doing the work twice. It makes retries safe.
Should we use an integration platform or write code?
A platform suits simple flows between common tools. Custom code suits complex logic, heavy volume or strict control. Many products use both.