Make Financial Webhooks Safe to Retry

Payment gateways retry when they do not receive a clear response, and the same webhook may arrive twice or concurrently. If the system credits an account on every delivery, one payment can increase the balance more than once.

Use the provider's stable, unique event or transaction identifier when available, or generate a UUID and idempotency key and persist it before the first request. Store the identifier under a UNIQUE constraint. Do not derive the key from a minute or timestamp alone; collisions and retries make that strategy unreliable.

Record the event and change the balance in one transaction, treating a unique-constraint conflict as a safe repeat rather than a new operation. Preserve the necessary state and payload for audit, and verify the provider signature before processing. Backups aid recovery, but they do not replace a design that prevents duplication as it happens.