An integration can look finished when a request succeeds in a demo. The real design questions appear later: the provider is slow, a webhook arrives twice, or a response never reaches your application. Those situations need explicit behavior.
Describe the business action first
Write down what the integration changes in your application. Does it mark an invoice as paid, synchronize a product or update a customer record? Name the local record, the external identifier and the conditions under which the change is allowed.
Keep the provider-specific request code separate from those business rules. That makes failures easier to investigate without scattering integration details throughout the application.
Plan for duplicate events
Stripe documents that webhook events can be delivered more than once and that delivery order is not guaranteed. For that integration, verify signatures and track processed events. A repeated notification should not create a second invoice or repeat a customer-facing action.
For other providers, check their documented delivery guarantees. Do not assume that all webhook systems behave identically.
Decide what happens after a timeout
A timeout leaves uncertainty: the remote action may have completed even though the response did not arrive. Before retrying a payment or another consequential operation, use the provider's supported reconciliation or idempotency mechanism.
Give retryable work a clear limit and a visible failure state. Staff should be able to tell whether an operation is pending, completed or waiting for attention.
Make support possible
Record useful identifiers, timings and outcomes while keeping secrets and sensitive payloads out of logs. A support conversation should be traceable from the local record to the external event.
Our recommended review includes successful requests, duplicate notifications, invalid signatures and interrupted requests. These scenarios help expose the assumptions hidden behind a successful demo.