From 1c721288cee65ce9767483cf784575e174cde55f Mon Sep 17 00:00:00 2001 From: Proxynth Date: Thu, 9 Jul 2026 17:31:19 +0200 Subject: [PATCH] docs: update post-hardening architecture documentation --- README.md | 17 ++++++++++++---- docs/best-practices.md | 2 +- docs/configuration.md | 7 +++++++ docs/facade-api.md | 45 ++++++++++++++++++++++++++--------------- docs/getting-started.md | 18 +++++++++++------ docs/services/github.md | 2 +- examples/README.md | 2 +- 7 files changed, 64 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index f89f376..1a55a48 100644 --- a/README.md +++ b/README.md @@ -448,6 +448,15 @@ public function handleWebhook(Request $request) } ``` +## Deduplication + +LaraWebhook separates audit logs from deduplication state. + +- `webhook_logs` stores the audit trail and dashboard/API read data. +- `processed_webhook_events` stores successfully processed webhook identities. +- Deduplication uses `service + idempotency_key`. +- `external_id` remains the provider delivery/event identifier. + --- ## 🎯 Facade & Enum API @@ -983,7 +992,7 @@ Successful webhook processing creates a log entry: **View webhook logs:** ```bash php artisan tinker ->>> \Proxynth\LaraWebhook\Models\WebhookLog::where('service', 'stripe')->latest()->first(); +>>> \Proxynth\Larawebhook\Audit\Infrastructure\Laravel\Persistence\Models\WebhookLog::where('service', 'stripe')->latest()->first(); ``` **Test with Stripe CLI:** @@ -1314,7 +1323,7 @@ Successful webhook processing creates a log entry: **View webhook logs:** ```bash php artisan tinker ->>> \Proxynth\LaraWebhook\Models\WebhookLog::where('service', 'github')->latest()->first(); +>>> \Proxynth\Larawebhook\Audit\Infrastructure\Laravel\Persistence\Models\WebhookLog::where('service', 'github')->latest()->first(); ``` **Test webhook delivery:** @@ -1906,7 +1915,7 @@ $logs = WebhookLog::service('github') ```bash # Check for recent failures php artisan tinker ->>> \Proxynth\LaraWebhook\Models\WebhookLog::where('status', 'failed') +>>> \Proxynth\Larawebhook\Audit\Infrastructure\Laravel\Persistence\Models\WebhookLog::where('status', 'failed') ->where('created_at', '>', now()->subHour()) ->count(); ``` @@ -2108,7 +2117,7 @@ Webhooks are logged in the `webhook_logs` table with: To view logs: ```bash php artisan tinker ->>> \Proxynth\LaraWebhook\Models\WebhookLog::latest()->get(); +>>> \Proxynth\Larawebhook\Audit\Infrastructure\Laravel\Persistence\Models\WebhookLog::latest()->get(); ``` --- diff --git a/docs/best-practices.md b/docs/best-practices.md index 0722649..0044968 100644 --- a/docs/best-practices.md +++ b/docs/best-practices.md @@ -143,7 +143,7 @@ public function handle(Request $request) ```bash php artisan tinker ->>> \Proxynth\Larawebhook\Models\WebhookLog::where('status', 'failed') +>>> \Proxynth\Larawebhook\Audit\Infrastructure\Laravel\Persistence\Models\WebhookLog::where('status', 'failed') ->where('created_at', '>', now()->subHour()) ->count(); ``` diff --git a/docs/configuration.md b/docs/configuration.md index 794bb40..f27fbd7 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -49,6 +49,13 @@ Configure automatic retry behavior for failed webhooks: ], ``` +* enabled: enables retry behavior. +* async: dispatches retry attempts to the queue when using the middleware. +* max_attempts: maximum number of attempts. +* delays: delay in seconds per retry attempt. + +Internally, retry settings are resolved through infrastructure config resolvers. Application use cases do not read Laravel config directly. + ### Async Retries When `async` is `true`: diff --git a/docs/facade-api.md b/docs/facade-api.md index 9353f6d..d20207d 100644 --- a/docs/facade-api.md +++ b/docs/facade-api.md @@ -1,30 +1,43 @@ -# Facade & Enum API - -LaraWebhook provides a powerful Facade and an Enum for type-safe service handling. -For the inbound request flow, see [Architecture](/architecture). For manual validation, always wrap raw signature headers with `Signature::fromString()`. - -## Role of the facade +# Facade API The `Larawebhook` facade is a Laravel-friendly public API. -It is intentionally a DX adapter over application use cases, repositories and Laravel infrastructure services. It should not be treated as the place where core webhook workflows are implemented. +It is a DX adapter over application use cases, read repositories and Laravel services. It should not be treated as the place where core webhook workflows are implemented. -Critical behavior belongs to dedicated use cases: +Critical workflows live in dedicated use cases: -- `ReceiveWebhook` for inbound middleware processing; -- `ValidateWebhook` for signature validation; -- `RecordWebhookLog` for audit persistence; -- `RetryWebhook` for retry attempts; -- `ReplayWebhook` for replay attempts. +- `ReceiveWebhook` +- `ValidateWebhook` +- `RecordWebhookLog` +- `RetryWebhook` +- `ReplayWebhook` For new code, prefer the high-level helpers: - `validate()` - `validateAndLog()` -- `validateWithRetries()` -- query/read helpers +- `validateWithRetries()` for simple synchronous/manual flows +- `logs()` +- `logsForService()` +- `failedLogs()` +- `successfulLogs()` +- `getFailureCount()` +- notification helpers when using LaraWebhook notifications +- service helpers such as `isServiceSupported()`, `supportedServices()`, `service()` + +## Legacy manual logging helpers + +`logSuccess()` and `logFailure()` remain available for compatibility. + +They are deprecated for new code. + +Prefer: + +- `validateAndLog()` when validating and recording a webhook; +- `RecordWebhookLog` when writing package/internal audit code; +- the middleware flow for normal inbound webhooks. -Manual logging helpers remain available for compatibility, but are deprecated. +Manual logging helpers write audit logs only. They do not create `processed_webhook_events` entries and therefore do not affect deduplication. ### Validation diff --git a/docs/getting-started.md b/docs/getting-started.md index 003e3d7..51d2819 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -67,12 +67,14 @@ Route::post('/github-webhook', function () { **What the middleware does:** -- ✅ Validates the webhook signature -- ✅ Runs `ReceiveWebhook`, which validates the payload, detects duplicates, and records the audit log -- ✅ Dispatches collected domain events for the HTTP adapter -- ✅ Rejects duplicate webhooks (returns `200 OK` with `already_processed`) -- ✅ Returns 403 for invalid signatures -- ✅ Returns 400 for missing headers or malformed payloads +- validates the provider signature; +- extracts the event type and provider external id when available; +- resolves an application idempotency key; +- rejects already processed webhooks using `processed_webhook_events`; +- records an audit log in `webhook_logs`; +- records successful processing in `processed_webhook_events`; +- optionally dispatches async retries; +- returns provider-safe HTTP responses. ### Manual Validation (Advanced) @@ -109,6 +111,10 @@ public function handleWebhook(Request $request) `Signature::fromString()` wraps the raw signature header in a typed value object so the application can carry the signature safely and, for providers that need it, keep timestamp metadata attached to the same object. +Manual facade flows are useful when you cannot use the middleware. + +For normal inbound webhooks, prefer the middleware because it also handles idempotency, duplicate detection, audit logging and async retry orchestration. + ## Architecture Notes - `ValidateWebhook` validates signatures and normalizes the provider-facing validation result. diff --git a/docs/services/github.md b/docs/services/github.md index 57760f7..5ee21e3 100644 --- a/docs/services/github.md +++ b/docs/services/github.md @@ -179,7 +179,7 @@ LaraWebhook automatically validates this signature. **View logs:** ```bash php artisan tinker ->>> \Proxynth\Larawebhook\Models\WebhookLog::where('service', 'github')->latest()->first(); +>>> \Proxynth\Larawebhook\Audit\Infrastructure\Laravel\Persistence\Models\WebhookLog::where('service', 'github')->latest()->first(); ``` ## Common Events diff --git a/examples/README.md b/examples/README.md index 3de236d..9645a76 100644 --- a/examples/README.md +++ b/examples/README.md @@ -350,7 +350,7 @@ php artisan tinker ```bash php artisan tinker ->>> \Proxynth\LaraWebhook\Models\WebhookLog::where('status', 'failed') +>>> \Proxynth\Larawebhook\Audit\Infrastructure\Laravel\Persistence\Models\WebhookLog::where('status', 'failed') ->where('created_at', '>', now()->subHour()) ->get(); ```