Reliable API Integrations: Webhooks, Retries and Laravel Boundaries

List the sending system, receiving system, event name, identifier, expected delay and business owner. Decide which system is authoritative for each field. A payment provider may own payment status while your application owns order fulfillment; treating either as authoritative for everything creates conflicting updates.

Use a small mapping table: source field, destination field, type, required state and failure action. Distinguish a missing value from an empty string or zero. Choose how currency, timestamps and external identifiers are stored before processing real data. Never infer that a payment succeeded merely because a browser reached a success page.

Consider an illustrative order whose payment event arrives twice. Receive the event, verify its authenticity using the provider’s documented method, persist its unique identifier and payload reference, and acknowledge receipt after durable acceptance. A background worker can then apply the business update.

The duplicate delivery should find the previously accepted identifier and avoid a second fulfillment action. Use a database uniqueness constraint or an equivalent atomic mechanism; a read followed by an unprotected insert can race under simultaneous requests. This is an architecture example, not a report from a named client system.

Keep a small state record: received, processing, succeeded or failed. Record attempt count and the last useful error. Do not log secrets or full payment details to make debugging convenient. Store only what operators need to reconcile the event.

An external side effect can succeed just before a local transaction fails. Retrying the whole job may then repeat it. Use the receiving provider’s idempotency mechanism where available and keep a reconciliation path for ambiguous outcomes. Exactly-once delivery should not be assumed from the presence of a queue.

Classify failures. A temporary timeout may be retryable; an invalid customer identifier needs correction. Use delayed retries with a cap, and respect provider limits. Unlimited immediate retries can turn a small outage into a backlog or an account restriction.

Laravel queues provide mechanisms for attempts, timeouts and failed jobs; use the documentation for the version installed in your project. Assign an owner for failed work. A dashboard that only shows successful events hides the cases where support actually needs help.

Deliveries may arrive late or out of order. Before applying a transition, check whether it is valid for the current order state. Where necessary, retrieve the provider’s current authoritative record. Avoid overwriting a newer confirmed state with an older notification.

Validate signatures according to the provider’s instructions, including any raw-body requirement. Keep live and test credentials separate. For your own APIs, enforce authorization on the resource, not just authentication of the caller. A user who can list their own orders must not be able to request another customer’s order by changing an ID.

Send the same event twice; submit two duplicates concurrently; deliver an older event after a newer one; simulate a timeout after the downstream system accepted the operation; and restart the worker during processing. Check both the final business state and the event history.

Also test an invalid signature, a missing required field, an unauthorized resource request and an unavailable dependency. Record the expected response and recovery action for each. Before launch, agree who receives alerts, how failed events are replayed and how the system is reconciled against the provider’s records.