Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 13 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:**
Expand Down Expand Up @@ -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:**
Expand Down Expand Up @@ -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();
```
Expand Down Expand Up @@ -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();
```

---
Expand Down
2 changes: 1 addition & 1 deletion docs/best-practices.md
Original file line number Diff line number Diff line change
Expand Up @@ -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();
```
Expand Down
7 changes: 7 additions & 0 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`:
Expand Down
45 changes: 29 additions & 16 deletions docs/facade-api.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down
18 changes: 12 additions & 6 deletions docs/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion docs/services/github.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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();
```
Expand Down