Payments Domain - Webhooks Documentation

"""
Key Features:
- HMAC-SHA256 signature verification
- Idempotency via WebhookEvent model
- Fast response times
- Minimal business logic - delegates to existing services
"""

@method_decorator(csrf_exempt, name='dispatch')
class StripeWebhookReceiver(APIView):
    """
    Secure webhook receiver for Stripe payment events.

    Responsibilities:
    1. Verify Stripe HMAC-SHA256 signature
    2. Check idempotency via WebhookEvent model
    3. Update payment status and link to line items
    4. Mark transaction as completed if fully paid
    5. Return fast 200 response

    Note: Inventory deduction happens automatically via signals
    when transaction status changes to COMPLETED.
    """

    authentication_classes = []  # Webhooks use signature verification
    permission_classes = []      # Webhooks use signature verification

GET /payments/webhook/stripe/

{
  "status": "ok",
  "message": "Stripe webhook endpoint is accessible",
  "endpoint": "/payments/webhook/stripe/",
  "methods": ["GET", "POST"]
}

logger.info("=== STRIPE WEBHOOK GET REQUEST ===")
logger.info(f"Request path: {request.path}")
logger.info("Stripe webhook endpoint is accessible")

POST /payments/webhook/stripe/
Content-Type: application/json
Stripe-Signature: t=1700000000,v1=abc123...

{
  "id": "evt_1234567890",
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_1234567890",
      "amount_received": 12550,
      ...
    }
  }
}

try:
    webhook_data = json.loads(request.body.decode('utf-8'))
except (json.JSONDecodeError, UnicodeDecodeError) as e:
    logger.error(f"Failed to parse webhook JSON: {e}")
    return Response(
        {'error': 'Invalid JSON payload'},
        status=status.HTTP_400_BAD_REQUEST
    )

{
  "error": "Invalid JSON payload"
}

if not self._is_signature_valid(request):
    logger.warning("Stripe webhook signature verification failed")
    return Response(
        {'error': 'Invalid webhook signature'},
        status=status.HTTP_401_UNAUTHORIZED
    )

{
  "error": "Invalid webhook signature"
}

event_id = webhook_data.get('id')
event_type = webhook_data.get('type')

if not event_id or not event_type:
    logger.error(f"Missing event ID or type in webhook: {webhook_data}")
    return Response(
        {'error': 'Missing event ID or type'},
        status=status.HTTP_400_BAD_REQUEST
    )

logger.info(f"Verified Stripe webhook: {event_type} ({event_id})")

{
  "error": "Missing event ID or type"
}

{
  "status": "duplicate",
  "message": "Webhook already processed",
  "event_id": "evt_1234567890"
}

{
  "status": "processing",
  "message": "Webhook is currently being processed",
  "event_id": "evt_1234567890"
}

try:
    result = self._process_webhook_event(webhook_event, webhook_data)

    # Mark as processed
    webhook_event.status = 'processed'
    webhook_event.processed_at = timezone.now()
    webhook_event.save(update_fields=['status', 'processed_at'])

    logger.info(f"Successfully processed Stripe webhook: {event_type} ({event_id})")

    return Response(
        {
            'status': 'success',
            'message': 'Webhook processed successfully',
            'event_id': event_id,
            'event_type': event_type,
            'result': result
        },
        status=status.HTTP_200_OK
    )

{
  "status": "success",
  "message": "Webhook processed successfully",
  "event_id": "evt_1234567890",
  "event_type": "payment_intent.succeeded",
  "result": {
    "success": true,
    "payment_id": "payment-uuid",
    "validation": "confirmed",
    "amount_match": true
  }
}

except Exception as e:
    logger.error(f"Failed to process Stripe webhook {event_id}: {e}", exc_info=True)

    # Mark as failed
    webhook_event.status = 'failed'
    webhook_event.error_message = str(e)
    webhook_event.save(update_fields=['status', 'error_message'])

    return Response(
        {
            'status': 'error',
            'message': 'Failed to process webhook',
            'event_id': event_id,
            'error': str(e)
        },
        status=status.HTTP_500_INTERNAL_SERVER_ERROR
    )

{
  "status": "error",
  "message": "Failed to process webhook",
  "event_id": "evt_1234567890",
  "error": "TransactionPayment matching query does not exist"
}

Stripe-Signature: t=1700000000,v1=abc123def456...

webhook_secret = getattr(settings, 'STRIPE_WEBHOOK_SECRET', None)
if not webhook_secret:
    logger.error("STRIPE_WEBHOOK_SECRET is not configured")
    return False

# .env file (NOT committed to git)
STRIPE_WEBHOOK_SECRET=whsec_abc123def456...

# Django settings.py
STRIPE_WEBHOOK_SECRET = os.environ.get('STRIPE_WEBHOOK_SECRET')

signature_header = request.headers.get('Stripe-Signature')
if not signature_header:
    logger.warning("Missing 'Stripe-Signature' header")
    return False

try:
    sig_map = {
        key_value.split('=')[0]: key_value.split('=')[1]
        for key_value in signature_header.split(',')
    }
    timestamp_str = sig_map.get('t')
    signature = sig_map.get('v1')

    if not timestamp_str or not signature:
        raise ValueError("Missing timestamp or signature in header")

    timestamp = int(timestamp_str)
except (ValueError, IndexError) as e:
    logger.error(f"Invalid signature header format: {signature_header} - {e}")
    return False

Input: "t=1700000000,v1=abc123"
Output:
  timestamp_str = "1700000000"
  signature = "abc123"
  timestamp = 1700000000

# Prevent replay attacks (5-minute tolerance)
if abs(time.time() - timestamp) > 300:
    logger.warning("Webhook timestamp validation failed (possible replay attack)")
    return False

# Construct the signed payload: timestamp_string.raw_body
signed_payload = f"{timestamp_str}.".encode('utf-8') + request.body

# Calculate expected signature
expected_signature = hmac.new(
    webhook_secret.encode('utf-8'),
    signed_payload,
    hashlib.sha256
).hexdigest()

timestamp_str = "1700000000"
request.body = b'{"id":"evt_123","type":"payment_intent.succeeded",...}'

signed_payload = b'1700000000.{"id":"evt_123","type":"payment_intent.succeeded",...}'

secret = "whsec_abc123"
payload = "1700000000.{...json...}"

signature = HMAC-SHA256(secret, payload)
# Output: "def456789abc..."

logger.debug("--- STRIPE SIGNATURE VERIFICATION ---")
logger.debug(f"Timestamp: {timestamp_str}")
logger.debug(f"Signature from header: {signature}")
logger.debug(f"Expected signature: {expected_signature}")

# Securely compare the signatures
return hmac.compare_digest(signature, expected_signature)

return signature == expected_signature  # Timing attack vulnerable

return hmac.compare_digest(signature, expected_signature)  # Constant-time comparison

with transaction.atomic():
    webhook_event, created = WebhookEvent.objects.get_or_create(
        event_id=event_id,
        defaults={
            'event_type': event_type,
            'processor': 'stripe',
            'status': 'pending',
            'raw_payload': webhook_data
        }
    )

    if not created:
        if webhook_event.status == 'processed':
            logger.info(f"Duplicate webhook detected - already processed: {event_id}")
            return Response(
                {
                    'status': 'duplicate',
                    'message': 'Webhook already processed',
                    'event_id': event_id
                },
                status=status.HTTP_200_OK
            )
        elif webhook_event.status == 'pending':
            logger.info(f"Webhook currently being processed: {event_id}")
            return Response(
                {
                    'status': 'processing',
                    'message': 'Webhook is currently being processed',
                    'event_id': event_id
                },
                status=status.HTTP_200_OK
            )

[New Event]
    ↓
get_or_create(event_id)
    ↓
┌─────────────┬─────────────┐
│   created   │ not created │
│  (new)      │  (duplicate)│
└─────┬───────┴──────┬──────┘
      ↓              ↓
status='pending'  Check status
      ↓              ↓
  Process      ┌─────┴─────┐
      ↓        │           │
  ┌───┴───┐  'processed' 'pending'
  │       │     ↓           ↓
success failure Return    Return
  ↓       ↓     200       200
'processed' 'failed'

class WebhookEvent(models.Model):
    event_id = models.CharField(max_length=255, unique=True)  # Uniqueness constraint

def _process_webhook_event(self, webhook_event, webhook_data):
    """
    Process the webhook event based on event type.

    Currently handles:
    - payment_intent.succeeded: Update payment status and complete transaction
    """
    event_type = webhook_data.get('type')

    if event_type == 'payment_intent.succeeded':
        return self._handle_payment_intent_succeeded(webhook_event, webhook_data)
    else:
        logger.info(f"Ignoring webhook event type: {event_type}")
        return {'handled': False, 'reason': 'event_type_not_supported'}

"""
Validate payment that was already processed by Electron POS.

This webhook serves as async validation/reconciliation, NOT payment processing.
Payment was already confirmed by Stripe Terminal before Django received it.
"""

def _handle_payment_intent_succeeded(self, webhook_event, webhook_data):
    from decimal import Decimal

    payment_intent = webhook_data.get('data', {}).get('object', {})
    payment_intent_id = payment_intent.get('id')
    amount_received = Decimal(str(payment_intent.get('amount_received', 0))) / Decimal('100')

    logger.info(f"Validating payment_intent.succeeded: {payment_intent_id}, amount: \${amount_received}")

    # Find payment by processor_transaction_id
    try:
        payment = TransactionPayment.objects.select_related('transaction').get(
            processor_transaction_id=payment_intent_id
        )

        # Validate amount matches
        if payment.amount != amount_received:
            logger.warning(
                f"Amount mismatch for {payment_intent_id}: "
                f"Django=\${payment.amount}, Stripe=\${amount_received}"
            )
        else:
            logger.info(f"Amount validated: \${amount_received}")

        # Link webhook to payment for audit trail
        webhook_event.payment = payment
        webhook_event.save(update_fields=['payment'])
        logger.info(f"Linked WebhookEvent {webhook_event.event_id} to payment {payment.id} for audit trail")

        logger.info(f"Webhook validated payment {payment.id} (already succeeded via Electron)")

        return {
            'success': True,
            'payment_id': str(payment.id),
            'validation': 'confirmed',
            'amount_match': payment.amount == amount_received
        }

    except TransactionPayment.DoesNotExist:
        # Race condition: Webhook arrived before Electron POST
        logger.info(
            f"Webhook for {payment_intent_id} - payment not yet created (Electron POST pending or test webhook)"
        )

        return {
            'success': True,
            'reason': 'payment_pending_creation',
            'webhook_stored': True
        }

payment_intent = webhook_data.get('data', {}).get('object', {})
payment_intent_id = payment_intent.get('id')
amount_received = Decimal(str(payment_intent.get('amount_received', 0))) / Decimal('100')

payment = TransactionPayment.objects.select_related('transaction').get(
    processor_transaction_id=payment_intent_id
)

if payment.amount != amount_received:
    logger.warning(
        f"Amount mismatch for {payment_intent_id}: "
        f"Django=\${payment.amount}, Stripe=\${amount_received}"
    )
else:
    logger.info(f"Amount validated: \${amount_received}")

webhook_event.payment = payment
webhook_event.save(update_fields=['payment'])
logger.info(f"Linked WebhookEvent {webhook_event.event_id} to payment {payment.id} for audit trail")

return {
    'success': True,
    'payment_id': str(payment.id),
    'validation': 'confirmed',
    'amount_match': payment.amount == amount_received
}

except TransactionPayment.DoesNotExist:
    # Race condition: Webhook arrived before Electron POST
    logger.info(
        f"Webhook for {payment_intent_id} - payment not yet created (Electron POST pending or test webhook)"
    )

    return {
        'success': True,
        'reason': 'payment_pending_creation',
        'webhook_stored': True
    }

# Queue async task to recheck in 5 seconds
from celery import current_app
current_app.send_task(
    'payments.tasks.retry_webhook_processing',
    args=[webhook_event.id],
    countdown=5  # Retry after 5 seconds
)

// POST /payments/terminal/create-payment/
const response = await fetch('/payments/terminal/create-payment/', {
  method: 'POST',
  body: JSON.stringify({
    amount: 12550,  // $125.50 in cents
    currency: 'usd'
  })
});

const { id, client_secret } = await response.json();
// id = "pi_abc123"
// client_secret = "pi_abc123_secret_xyz"

# PaymentService._process_stripe_payment()
intent = stripe.PaymentIntent.create(
    amount=12550,
    currency='usd'
)
# Returns: {id: "pi_abc123", client_secret: "pi_abc123_secret_xyz"}

// Use Stripe Terminal SDK
const terminal = StripeTerminal.create({
  onFetchConnectionToken: async () => {
    const response = await fetch('/payments/terminal/connection-token/', {
      method: 'POST'
    });
    const { secret } = await response.json();
    return secret;
  }
});

// Collect payment
const result = await terminal.collectPaymentMethod(client_secret);
const payment = await terminal.processPayment(result.paymentIntent);
// payment.status = "succeeded"

POST https://yourdomain.com/payments/webhook/stripe/
Stripe-Signature: t=1700000000,v1=abc123...

{
  "id": "evt_xyz789",
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_abc123",
      "amount_received": 12550,
      "status": "succeeded"
    }
  }
}

// After terminal.processPayment succeeds
const paymentRecord = await fetch('/payments/payments/', {
  method: 'POST',
  body: JSON.stringify({
    transaction: transactionId,
    payment_method: paymentMethodId,
    amount: "125.50",
    status: "succeeded",  // Already succeeded at terminal
    processor_transaction_id: "pi_abc123",  // Link to Stripe PaymentIntent
    processed_at: new Date().toISOString()
  })
});

# Find payment by processor_transaction_id
payment = TransactionPayment.objects.get(
    processor_transaction_id="pi_abc123"
)

# Validate amount
if payment.amount == Decimal("125.50"):
    logger.info("Amount validated")

# Link webhook to payment
webhook_event.payment = payment
webhook_event.save()

0ms    POS: Create PaymentIntent
       ↓
100ms  Terminal: Collect card
       ↓
200ms  Stripe: Process payment → SUCCEEDED
       ├─→ 250ms: Send webhook
       └─→ 300ms: POS creates Django payment
                  ↓
              350ms: Webhook processes (payment found)
                    ↓
                  Validation complete

0ms    POS: Create PaymentIntent
       ↓
100ms  Terminal: Collect card
       ↓
200ms  Stripe: Process payment → SUCCEEDED
       ├─→ 250ms: Send webhook
       │          ↓
       │      300ms: Webhook processes (payment NOT found)
       │            ↓
       │          Webhook stored, return success
       │
       └─→ 400ms: POS creates Django payment
                  ↓
              Payment created (webhook already stored)

brew install stripe/stripe-cli/stripe
stripe login

stripe listen --forward-to localhost:8000/payments/webhook/stripe/

> Ready! Your webhook signing secret is whsec_abc123... (^C to quit)

STRIPE_WEBHOOK_SECRET=whsec_abc123...

stripe trigger payment_intent.succeeded

INFO: === STRIPE WEBHOOK ENDPOINT HIT ===
INFO: Verified Stripe webhook: payment_intent.succeeded (evt_...)
INFO: Webhook for pi_... - payment not yet created (test webhook)
INFO: Successfully processed Stripe webhook: payment_intent.succeeded (evt_...)

curl http://localhost:8000/payments/webhook/stripe/

{
  "status": "ok",
  "message": "Stripe webhook endpoint is accessible"
}

# Get timestamp
timestamp=$(date +%s)

# Construct payload
payload='{"id":"evt_test","type":"payment_intent.succeeded"}'

# Calculate signature
signature=$(echo -n "\${timestamp}.\${payload}" | openssl dgst -sha256 -hmac "whsec_YOUR_SECRET" | sed 's/^.* //')

# Send request
curl -X POST http://localhost:8000/payments/webhook/stripe/ \
  -H "Content-Type: application/json" \
  -H "Stripe-Signature: t=\${timestamp},v1=\${signature}" \
  -d "\${payload}"