Operator Guide

This guide is for technical operators maintaining the eCommerce backend. It links to the detailed runbooks in the repository.

NOTE

"Technical operator" is a reader persona, not a codebase role. The operational tasks below are performed with admin/infra access.

Setup

• The commerce engine is LunarPHP (lunarphp/lunar).
• Stripe PHP SDK is stripe/stripe-php at ^19.4.

Detailed one-time setup: see docs/operations/shopper-install.md in the repository (not yet published in this docs app).

Webhooks

• Stripe sends events to /api/webhooks/stripe (Laravel route — no /v1 segment).
• The event's event_id is inserted atomically before the processing job is dispatched, so repeat deliveries do not enqueue a second job.
• The 300-second signature tolerance only validates the Stripe signature timestamp; it is not the idempotency window.

Rotation runbook: docs/operations/stripe-webhook-rotation.md — rotate with a 24-hour overlap window.

Secret rotation

• APP_KEY: rotating it breaks the encrypted account_number on disbursements. Re-encrypt affected records after rotation. Runbook: docs/operations/app-key-rotation.md
• Ingestion tokens: rotate weekly.

Push token cleanup

WARNING

The is_active column for push tokens is not yet deployed. Only cleanup Strategy C currently works; Strategies A/B are not effective until the migration lands.

Runbook: docs/operations/push-token-cleanup.md

Troubleshooting

Symptom	Likely cause	Action
Webhook 404	Wrong path	Use /api/webhooks/stripe (no /v1)
Duplicate events processed	Idempotency missed	Verify the unique event_id row and queue worker health.
Payout fails	Manual Mobanking only	Bank-account payout is not implemented.

See the Stripe Webhook Reference for the full event contract.