Payment Webhooks Must Be Idempotent

Payment webhooks may be retried when a provider does not receive a timely successful response. Your application must be able to process the same event more than once without creating duplicate orders, credits, or fulfillment actions.

Verify the provider's signature using the documented method and the raw request body where required. Reject invalid signatures and avoid trusting a browser redirect as proof of payment. Record the provider's event or transaction identifier and enforce uniqueness at the database layer where possible.

Process state transitions deliberately. A repeated successful-payment event should not create a second fulfillment, and an event arriving out of order should not downgrade a completed order. Use transactions to keep related local changes consistent, and move slow work to a queue after safely recording the event.

Return the expected acknowledgement promptly, log a correlation identifier, and provide a way to replay failed events safely. Test duplicate delivery, delayed delivery, invalid signatures, timeouts, and partial failures before launch. Idempotency is a business correctness requirement, not merely a performance optimization.