Phase 3: Webhooks & Asynchronous Fulfillment

This document details the non-blocking, asynchronous architecture used to finalize orders and provision digital goods (subscriptions, trip packages, and forks).

Because payment gateways operate over the open internet, our webhook system is designed with extreme paranoia: assuming every payload is potentially forged, duplicated, delayed, or concurrent.

1. Webhook Ingestion & Security (HMAC)

When Paymob processes a payment, it fires a POST request to our /api/webhooks/paymob endpoint. This hits the PaymobWebhookController::handle method, which immediately delegates to the WebhookService.

The SEC-05 HMAC Guard

Before parsing any payload data, the system strictly validates the HMAC SHA-512 signature provided in the query string.
If the application is running in production and the PAYMOB_HMAC environment variable is empty, the PaymobGateway throws a fatal exception. This fails-fast, preventing attackers from exploiting an empty-secret HMAC bypass.

2. Concurrency & Grace Period Guards

Once the payload is cryptographically verified, the WebhookService applies three layers of defense before touching the database.

Concurrency Lock: We acquire an atomic lock via Redis: Cache::lock("paymob_webhook_processing_{$merchantOrderId}", 60). If Paymob fires 5 identical webhooks simultaneously (network retries), 4 of them will hit the lock and gracefully return 200 OK without touching the DB.

Double-Processing Guard: We check if $payment->status is already PAID or FAILED.

The 24-Hour Grace Period (D5 Rule): An order is only valid for 24 hours. If a delayed "success" webhook arrives 48 hours later, we reject fulfillment to prevent granting entitlements on expired terms.

3. Webhook Processing Flowchart

The following diagram maps the exact execution path inside the WebhookService.

4. Asynchronous Provisioning: `FulfillOrderListener`

We strictly separate Order Status tracking (done in the Webhook Service) from Digital Goods Provisioning (done asynchronously in Event Listeners).

When the PaymentSucceeded event fires, the FulfillOrderListener takes over on the background queue. It iterates through the $order->items and determines the fulfillment strategy based on the product type.

Subscription Provisioning & Idempotency

If the user purchased a Subscription Plan, the listener:

Idempotency Check: Verifies if a subscription with the provider_ref matching the paymob_transaction_id already exists. If yes, it aborts (preventing double-upgrades).

Overlap Cleanup: Updates any currently ACTIVE subscriptions for that user to CANCELLED.

Activation: Creates the new Subscription record with the correct billing cycle.

AI Quota Reset: Resets the user's ai_generations_count to 0 and extends the ai_reset_at date.

5. Architectural Principles Applied

Pessimistic Ingestion: Webhooks trust nothing. They verify cryptography, concurrency, state, and time before acting.

Event-Driven Decoupling: The HTTP response to Paymob does not wait for email notifications to send or databases to provision logic. The Event bus cleanly breaks the execution thread.

Idempotent Listeners: Because Laravel queue workers can experience "At Least Once" delivery, the FulfillOrderListener checks the database state before executing any mutations, guaranteeing safety on retries.

Phase 3: Webhooks &amp; Asynchronous Fulfillment

1. Webhook Ingestion & Security (HMAC)#

The SEC-05 HMAC Guard#

2. Concurrency & Grace Period Guards#

3. Webhook Processing Flowchart#

4. Asynchronous Provisioning: FulfillOrderListener#

Subscription Provisioning & Idempotency#

5. Architectural Principles Applied#