Describe the business event first
An integration connects responsibilities, not just endpoints. Define the event, the source of truth and the action the destination should perform. For example, an approved proposal might create a project record. Decide who can approve it, which fields are required and what should happen when the destination is unavailable.
Write a contract both sides can validate
Specify identifiers, timestamps, field limits, required values and version behavior. Validate payloads at the boundary and reject ambiguous input. Do not silently guess a currency, country or customer account. Keep a sample contract with synthetic records and use it to test changes before they reach the real workflow.
Protect credentials and callbacks
Store secrets server-side, request only necessary permissions and rotate access when ownership changes. Validate webhook signatures according to the provider's current documentation. A public callback URL is not authorization. Restrict outbound destinations where user-supplied URLs are involved, and avoid fetching arbitrary internal network addresses.
Assume events can arrive twice
Networks fail after an action completes as well as before it starts. Use stable event references, uniqueness constraints and idempotent destination calls where supported. Distinguish retryable errors from invalid requests. Reconcile local and remote states so an operator can investigate a missing or duplicated action rather than blindly replaying everything.
Give exceptions an owner
Build an exception queue with safe context, attempt count and a documented recovery action. Alert on sustained failures without flooding staff with duplicate messages. Test revoked credentials, schema changes, timeouts and partial success. A good integration is one the business can understand and recover, not merely one that succeeds during a demonstration.
A practical planning checklist
Draw the source and destination states for one integration event. Mark the point where a side effect becomes irreversible and the reference used to deduplicate it. Ask an operator to explain how they would recover a partial failure using the proposed audit view. If recovery requires a developer to guess which remote action occurred, refine the design before launch.
