A third-party integration contract you can operate.
Define identity and completion evidence alongside payloads and endpoints. Keep provider uncertainty visible, validate webhook and response semantics, and give unresolved customer operations a named owner and repair path.
Inside this article 7 sections +
A third-party integration contract should describe identity, business outcomes, timing, failure behavior, and evidence of reconciliation. An endpoint URL and payload schema are insufficient when the provider can change behavior, deliver webhooks repeatedly, or accept a request before the client sees a response.
The contract should tell the application team how to operate the integration after launch: who owns an unresolved customer operation, what can be retried, and how the final result is established.
Contract one customer outcome
Consider an illustrative shipping integration that creates a label for an order. The customer expects one usable label associated with the correct account and shipment. The integration must distinguish a local request, provider acceptance, label creation, and a downloadable result.
Assign a durable local operation ID before contacting the provider. Map the internal account and shipment identifiers to the provider's account and object identifiers. Keep that mapping explicit when several customers use separate provider accounts or credentials.
Define which system owns each fact. The application owns customer permission and local order state. The provider owns whether its label was created and its external status. Neither side's display name should silently become the other's stable join key.
Record provider capabilities and their limits
Verify the provider's idempotency support, lookup methods, pagination, rate limits, webhook behavior, and versioning policy. Record the exact endpoint or API version used and the assumptions the application makes. Do not generalize from another endpoint in the same provider.
If a write times out, the safest next action may be a status lookup using a provider key rather than another create request. If the provider offers no reliable duplicate prevention or lookup, state that limitation and design a controlled unresolved state instead of claiming exactly-once behavior.
Document authentication and credential rotation by provider account. A single shared credential may simplify implementation but expand the consequences of exposure or revocation. The operating model should match the customer's account ownership and support responsibilities.
Validate responses without breaking on safe additions
Validate fields required for business correctness, including identifiers, status values, amount or unit semantics where relevant, and timestamps. Preserve unknown optional fields only when needed; do not let a harmless additive field break every request through an unnecessarily closed parser.
Treat unknown state values deliberately. A provider adding a new nonterminal state should not automatically make the application mark the shipment complete. Route unsupported states to a visible holding or reconciliation path and capture enough sanitized evidence to update the adapter.
Keep provider-specific transformations behind an adapter. Product code should consume a stable internal result such as pending, completed, rejected, or unresolved, with the provider reference retained for diagnosis. Avoid leaking dozens of vendor status strings throughout the application.
Treat webhooks as evidence to validate
Verify signatures using the provider's documented method and preserve the required raw request representation for verification. Enforce the intended replay or timestamp rules where supported. A JSON object with a familiar event name is not proof that the provider sent it.
Expect duplicate delivery and verify ordering guarantees instead of assuming them. Stripe, for example, documents that webhook events may be duplicated and are not guaranteed to arrive in generation order. That behavior illustrates why each integration must define its own event identity and state transition rules.
Persist a validated receipt before acknowledging when the workflow requires durable processing. Apply state changes idempotently and prevent an older event from overwriting a newer known result. Fetch the current provider object when that is the documented way to resolve incomplete or out-of-order evidence.
Test sandbox gaps explicitly
A sandbox may not reproduce live quotas, asynchronous delays, fraud controls, account permissions, or every error type. Keep a list of behavior it can demonstrate and behavior that remains unverified. Do not turn a successful test call into a claim that production failure recovery is complete.
Build local fixtures for timeout after acceptance, duplicate webhook, out-of-order status, malformed response, expired credential, and provider throttling. Use test accounts and synthetic shipments. Record the expected local operation state and the evidence required to leave an unresolved state.
Test the account boundary with two customer configurations. A retry or webhook must not select the wrong provider credential because the handler uses a current global setting instead of the operation's recorded provider account.
Track provider change notices and deprecation dates against the adapter version actually deployed. A notice becomes useful only when someone identifies affected endpoints, tests the proposed change, and schedules the migration. Include a fallback or holding state for changes that cannot be completed before support ends.
Make recovery part of the implementation you buy
Scope a first integration around one customer outcome and the provider operations required to complete it. Include identity mapping, authentication boundaries, completion evidence, and support ownership. State whether historical migration, bidirectional synchronization, and additional objects belong in the same commitment. Each can introduce separate reconciliation rules that a simple connector estimate may omit.
Request a versioned adapter contract, synthetic acceptance fixtures, a visible unresolved-operation state, and a receiving-team runbook. Have the delivery team demonstrate a timeout after a possible remote write and show how an operator distinguishes it from a request that never arrived. If the provider cannot supply a stable operation key or a way to inspect the result, that is a design constraint to resolve explicitly before automatic retries are enabled.
The local experiment below makes the lost-acknowledgment case reproducible using two SQLite databases. It demonstrates the logic under a receiver that supports idempotency. Your actual integration still needs tests against the provider's semantics and concurrent execution model. We can start with a provider probe when those capabilities are uncertain, then implement the accepted contract and recovery path as a bounded delivery.
Give the integration an operating owner
Expose accepted-but-unresolved operations, oldest pending age, repeated authentication failures, and unsupported provider states. Assign an owner who can inspect sanitized evidence and execute the documented repair. Keep retry controls separate from the ability to issue new business actions.
The job reconciliation guide helps locate incomplete operations, while event contract ownership helps manage consumers of the integration's results. Software implementation can connect these contracts, adapters, and operating checks into an integration that remains supportable when the provider or workload changes.