1. Describe the business operation and data contract
Start with the task the integration must complete: creating a customer, checking availability, updating a support ticket or retrieving a document. Identify the system that owns each record and the direction in which changes are allowed to travel.
For each operation, agree required fields, data types, identifiers, validation rules, response formats and error behaviour. Decide how missing values differ from empty values and how dates, time zones and monetary amounts are represented.
An OpenAPI description can document HTTP API operations, schemas, responses and security requirements in a machine-readable form. It helps establish the contract, but does not prove that an implementation follows it. Pair the description with tests and realistic examples. Read the OpenAPI specification.
2. Check permissions at the record level
Authentication identifies a caller; authorisation decides what that caller may do. Test both the operation and the particular record requested. A valid login should not automatically grant access to another customer’s records.
Use a separate integration identity with the permissions it needs. Plan credential storage and rotation, keep secrets out of client-side code and URLs, and decide which sensitive fields must be redacted from logs.
OWASP’s API security guidance highlights risks involving object-level and function-level authorisation, resource consumption and unsafe use of upstream APIs. Use these as review prompts for the relevant endpoints, rather than treating a successful request as proof of security. Explore the OWASP API Security Top 10.
3. Make retries a deliberate design decision
A timeout does not always mean an operation failed. The remote system may have completed the change before its response was lost. Repeating a write without a duplicate-protection strategy can create an extra order, payment or record.
Check whether the provider supports idempotency, how keys are scoped and how long results are retained. For example, Stripe documents an idempotency-key mechanism for safely repeating supported requests; the exact behaviour varies by API version. Do not assume that another provider follows the same rules. See Stripe’s idempotent-request documentation.
Illustrative failure scenario
Your CRM sends a request to create a record, then loses the response. The recovery process should check the operation’s identity or reconcile the remote result before creating a new record. Reusing a supported idempotency key may be part of that design; a different key represents a different attempt to the provider.
Set finite timeouts and retry limits. Distinguish transient failures from validation and permission errors, and honour the provider’s rate-limit guidance. Decide where unresolved work goes for an operator to review.
4. Treat incoming events as another interface
If the provider uses webhooks, document event types, signature verification, delivery identifiers and acknowledgement requirements. Validate the source using the provider’s supported method, and make repeated delivery safe.
GitHub recommends subscribing only to needed events, using a webhook secret, retaining HTTPS verification and responding promptly. Those are useful design prompts; the exact response deadline and retry behaviour must come from the provider you integrate with. Read GitHub’s webhook practices.
Define whether the receiver can queue work and acknowledge receipt before processing it. Consider delayed or out-of-order events, and provide a reconciliation path when events are missed. Do not rely on an event arriving exactly once.
5. Agree the evidence needed for handover
Test the integration in an approved test environment using non-sensitive fixtures. Include success, invalid data, an unauthorised record, an expired credential, a timeout and duplicate delivery where applicable. Define which system or queue shows unfinished work.
- Operation owners, data mappings and source-of-truth rules are documented.
- Permitted identities and record-level access tests are agreed.
- Timeout, duplicate-protection and retry behaviour are demonstrated.
- Webhook authentication and replay handling are covered where relevant.
- Logs provide useful correlation without exposing secrets or unnecessary personal data.
- Rate limits, provider version changes and operational escalation have named owners.
Bring the provider documentation, sample payloads with sensitive data removed and the business acceptance scenarios to a project discussion. These details make an integration estimate more meaningful than a count of endpoints alone.