👋 Welcome to Order Management + Webhooks

// routes/api.php - Rate limiting via middleware
Route::post('/webhooks/payments', [WebhookController::class, 'store'])
    ->middleware('webhook.rate.limit:1000,1');

// WebhookController.php - Clean separation of concerns
public function store(WebhookPaymentRequest $request): JsonResponse
{
    $startTime = microtime(true);
    
    // CRITICAL: Duplicate detection using cache for high performance
    $validatedData = $request->validated();
    $txnId = $validatedData['txn_id'];
    $cacheKey = "webhook_txn:{$txnId}";
    
    if (Cache::has($cacheKey)) {
        return response()->json(['message' => 'Duplicate webhook detected'], 409);
    }
    
    // CRITICAL: Create webhook log and dispatch job with high priority
    $webhookLog = WebhookLog::create([...]);
    ProcessPaymentWebhookJob::dispatch($webhookLog->id)
        ->onQueue('webhooks-high-priority');
    
    $processingTime = round((microtime(true) - $startTime) * 1000, 2);
    
    return response()->json([
        'message' => 'Webhook received and queued for processing',
        'processing_time_ms' => $processingTime,
    ], 202);
}

// Check if external_txn_id already exists
if ($payload['txn_id'] && Order::withExternalTxnId($payload['txn_id'])->exists()) {
    Log::info("Transaction ID {$payload['txn_id']} already processed, ignoring webhook");
    $webhookLog->markAsIgnored('Transaction already processed');
    return;
}

// Cache-based duplicate prevention
Cache::put($cacheKey, true, 300); // 5 minutes cache

// Database unique constraint on external_txn_id
Schema::table('orders', function (Blueprint $table) {
    $table->unique('external_txn_id');
});

// CRITICAL: Use database transaction with optimistic locking
DB::transaction(function () use ($webhookLog, $payload, $startTime) {
    // CRITICAL: Get order without locking (optimistic approach)
    $order = Order::where('id', $payload['order_uuid'])->first();
    
    // CRITICAL: Optimistic locking - update with version check
    $updatedRows = Order::where('id', $order->id)
        ->where('updated_at', $order->updated_at) // Optimistic lock
        ->update([
            'status' => $newStatus,
            'external_txn_id' => $payload['txn_id'],
            'amount' => $payload['amount'],
            'updated_at' => now(),
        ]);

    // CRITICAL: Check if update succeeded (optimistic locking)
    if ($updatedRows === 0) {
        Log::warning("Optimistic lock failed for order {$order->id} - another process modified it");
        throw new \Exception('Optimistic lock failed - order was modified by another process');
    }
    
    // Create audit trail and update webhook log within same transaction
    OrderEvent::create([...]);
    $webhookLog->markAsProcessed($processingTime);
});

class ProcessPaymentWebhookJob implements ShouldQueue
{
    public int $tries = 5;
    public int $timeout = 60;
    
    /**
     * Calculate the number of seconds to wait before retrying the job.
     * Optimized for database transaction conflicts and deadlocks.
     */
    public function backoff(): array
    {
        return [5, 10, 30, 60, 120]; // 5s, 10s, 30s, 1m, 2m
    }
    
    public function handle(): void
    {
        try {
            // CRITICAL: Use database transaction with optimistic locking
            DB::transaction(function () use ($webhookLog, $payload, $startTime) {
                // Process webhook with optimistic locking
                $order = Order::where('id', $payload['order_uuid'])->first();
                
                $updatedRows = Order::where('id', $order->id)
                    ->where('updated_at', $order->updated_at)
                    ->update([...]);
                
                if ($updatedRows === 0) {
                    throw new \Exception('Optimistic lock failed');
                }
            });
        } catch (\Exception $e) {
            // Handle optimistic lock failures - these should be retried
            if (str_contains($e->getMessage(), 'Optimistic lock failed')) {
                Log::warning("Optimistic lock failed for webhook {$this->webhookLogId}, will retry");
                throw $e; // Re-throw to trigger retry mechanism
            }
            throw $e;
        }
    }
}

// Insert new row in order_events (audit trail)
OrderEvent::create([
    'order_id' => $order->id,
    'from_status' => $oldStatus,
    'to_status' => $newStatus,
    'reason' => OrderEvent::REASON_WEBHOOK_PAYMENT,
    'metadata' => [
        'webhook_log_id' => $webhookLog->id,
        'txn_id' => $payload['txn_id'],
        'timestamp' => $payload['timestamp'],
        'amount' => $payload['amount'],
        'webhook_source' => $webhookLog->webhook_source,
        'correlation_id' => $webhookLog->correlation_id,
    ],
]);

// Webhook log tracking
$webhookLog = WebhookLog::create([
    'order_uuid' => $validatedData['order_uuid'],
    'txn_id' => $txnId,
    'raw_payload' => $validatedData,
    'status' => WebhookLog::STATUS_PENDING,
    'attempts' => 1,
    'webhook_source' => $validatedData['webhook_source'] ?? WebhookLog::SOURCE_UNKNOWN,
    'correlation_id' => $validatedData['correlation_id'] ?? null,
]);

{
    "order_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "txn_id": "TXN_123456789",
    "status": "paid",
    "amount": 99.99,
    "timestamp": "2024-01-15T10:30:00Z",
    "webhook_source": "payment_gateway",
    "correlation_id": "CORR_789",
    "metadata": {
        "payment_method": "credit_card",
        "card_last_four": "1234",
        "currency": "USD",
        "customer_id": "CUST_456"
    }
}

curl -X POST http://localhost:8000/api/webhooks/payment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "order_uuid": "550e8400-e29b-41d4-a716-446655440000",
    "txn_id": "TXN_123456789",
    "status": "paid",
    "amount": 99.99,
    "timestamp": "2024-01-15T10:30:00Z",
    "webhook_source": "payment_gateway",
    "correlation_id": "CORR_789",
    "metadata": {
        "payment_method": "credit_card",
        "card_last_four": "1234",
        "currency": "USD",
        "customer_id": "CUST_456"
    }
}'

{
    "message": "Webhook received and queued for processing",
    "webhook_log_id": 12345,
    "txn_id": "TXN_123456789",
    "status": "queued",
    "processing_time_ms": 15.23
}