A payment provider sends your server a webhook. Your server is busy, so the provider doesn't hear back in time, and it sends the same webhook again. Now two copies are on their way.

If your code adds a payment for each one, the customer is recorded as paying twice. If it sends a welcome email for each, they get two.

Duplicates aren't a rare bug. They're how most webhook systems are designed to work. This guide explains why, shows the tempting fixes that fail, and builds an inbox that handles duplicates, slow workers and crashes. It uses only Python and SQLite, and all of it is tested.

If webhooks are new to you, start with what a webhook is and how it works .

Why duplicates happen

Most webhook providers promise at least once delivery. They'll keep trying until they hear that you got it, so a message may arrive more than once, but a message is rarely lost.

That's a sensible choice for them. Losing a payment event is worse than sending it twice. But it hands the problem to you.…