API Idempotency

What we're doing: Make payment creation safe to retry, letting the database refuse duplicates rather than checking for them.

class PaymentCreateView(APIView):
    def post(self, request):
        key = request.headers.get("Idempotency-Key")
        if not key:
            raise ValidationError({"detail": "Idempotency-Key header is required."})

        fingerprint = sha256(request.body).hexdigest()

        try:
            with transaction.atomic():
                record = IdempotencyRecord.objects.create(
                    account=request.user.account, key=key, request_fingerprint=fingerprint)
                payment = charge_and_record(request.user.account, request.data)
                record.status_code = 201
                record.response_body = PaymentSerializer(payment).data
                record.save(update_fields=["status_code", "response_body"])
        except IntegrityError:
            record = IdempotencyRecord.objects.get(
                account=request.user.account, key=key)
            if record.request_fingerprint != fingerprint:
                raise Conflict("This Idempotency-Key was used with a different body.")
            if record.status_code is None:
                raise Conflict("The original request is still in progress.")
            return Response(record.response_body, status=record.status_code)

        return Response(record.response_body, status=201)

4–5

Requiring the header rather than defaulting to "no key" — an unkeyed payment request is a client bug, and failing loudly is better than silently accepting one that cannot be retried safely.

10–16

One transaction covers the key row, the charge, and the stored response. Either all three commit or none do, which is what stops the key and the charge from disagreeing.

17–19

The `IntegrityError` from the unique constraint *is* the duplicate check. Reading first and inserting after leaves a window where two concurrent retries both find nothing.

20–21

Same key, different body is a client bug, not a replay — returning the first result would silently discard the second request.

22–23

A key row with no stored status means the original attempt is still running. Answering 409 tells the client to wait rather than issuing a second charge.

Why this works: Letting the unique constraint decide removes the read-then-write race entirely: two simultaneous retries race to `INSERT`, exactly one wins, and the loser is routed to the replay path by the database rather than by a check that could have been stale.

What we're doing: A webhook endpoint that survives redelivery: verify, deduplicate, enqueue, and answer fast.

class StripeWebhookView(APIView):
    authentication_classes = []
    permission_classes = [AllowAny]

    def post(self, request):
        event = verify_signature(request.body, request.headers["Stripe-Signature"])

        try:
            with transaction.atomic():
                ProcessedEvent.objects.create(source="stripe", external_id=event["id"])
        except IntegrityError:
            return Response(status=200)          # already handled — tell Stripe to stop

        handle_stripe_event.delay(event["id"], event["type"])
        return Response(status=200)              # answer fast; the work happens elsewhere


@shared_task(acks_late=True, max_retries=5)
def handle_stripe_event(event_id, event_type):
    with transaction.atomic():
        record = (ProcessedEvent.objects
                  .select_for_update()
                  .get(source="stripe", external_id=event_id))
        if record.completed_at is not None:
            return                                # the task itself was redelivered

        apply_event(event_id, event_type)
        record.completed_at = timezone.now()
        record.save(update_fields=["completed_at"])

6

Signature verification comes first and unconditionally. A webhook endpoint is unauthenticated by necessity, so the signature is the only thing distinguishing a real event from anyone who knows the URL.

9–12

The insert *is* the duplicate check. Returning 200 for a duplicate is deliberate: any other status tells the provider to keep retrying work that is already done.

14–15

Enqueue and answer. Providers time out in seconds and retry on timeout, so doing the work inline turns one slow event into a redelivery storm.

18

`acks_late=True` acknowledges only after the task returns, so a worker crash means redelivery rather than a lost event — which is safe precisely because the task is idempotent.

21–25

The task deduplicates again, because at-least-once applies to the queue too. `select_for_update()` serialises two workers that both picked up the same redelivered message.

Why this works: Deduplicating at both hops — the HTTP delivery and the queue delivery — is not redundant: each hop has its own at-least-once guarantee, so each needs its own guard. The endpoint stays fast, and a crash anywhere produces a retry that lands on a no-op.