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
33 changes: 26 additions & 7 deletions docs/facade-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,28 @@
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()`.

## Larawebhook Facade
## Role of the facade

The `Larawebhook` facade provides a fluent API for all webhook operations.
Prefer `validate()`, `validateAndLog()`, `validateWithRetries()`, and the read/query helpers for new code.
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.

Critical behavior belongs to dedicated use cases:

- `ReceiveWebhook` for inbound middleware processing;
- `ValidateWebhook` for signature validation;
- `RecordWebhookLog` for audit persistence;
- `RetryWebhook` for retry attempts;
- `ReplayWebhook` for replay attempts.

For new code, prefer the high-level helpers:

- `validate()`
- `validateAndLog()`
- `validateWithRetries()`
- query/read helpers

Manual logging helpers remain available for compatibility, but are deprecated.

### Validation

Expand All @@ -20,13 +38,14 @@ Larawebhook::validate($payload, $signature, 'stripe');
$log = Larawebhook::validateAndLog($payload, $signature, 'github', 'push');
```

### Logging
#### Logging

Manual logging helpers remain available for compatibility, but they are deprecated.

The manual logging helpers remain available for compatibility, but they are deprecated.
Prefer `validateAndLog()` or the corresponding application use case when you need to persist an audit log.
Prefer `validateAndLog()` when a webhook should be validated and persisted, or use `RecordWebhookLog` directly when writing internal package code.

```php
// Log webhooks manually
// Deprecated manual audit helpers
Larawebhook::logSuccess('stripe', 'payment.succeeded', $payload);
Larawebhook::logFailure('stripe', 'payment.failed', $payload, 'Card declined');
```
Expand Down
42 changes: 27 additions & 15 deletions src/Shared/Application/Larawebhook.php
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,14 @@
use Proxynth\Larawebhook\Shared\Domain\Enums\WebhookService;

/**
* Main entry point for the Larawebhook package.
* Laravel-friendly public API for LaraWebhook.
*
* Provides a fluent API for webhook validation, logging, and querying.
* Prefer validate(), validateAndLog(), validateWithRetries(), and the read helpers.
* This class intentionally acts as a DX adapter around application use cases,
* repositories, and Laravel infrastructure services.
*
* It is not a pure application use case.
* Critical workflows should remain implemented in dedicated use cases such as
* ValidateWebhook, ReceiveWebhook, RetryWebhook, ReplayWebhook, and RecordWebhookLog.
*/
class Larawebhook
{
Expand Down Expand Up @@ -55,7 +59,7 @@ public function validate(string $payload, Signature $signature, string|WebhookSe
$webhookService = $this->resolveService($service);
$rawPayload = RawPayload::fromString($payload);

$secret = $this->getSecretResolver()->resolve($webhookService);
$secret = $this->getSecret($webhookService);

if ($secret === null || $secret === '') {
throw new WebhookException("No secret configured for service: {$webhookService->value}");
Expand Down Expand Up @@ -98,7 +102,10 @@ public function validateAndLog(
}

/**
* Validate a webhook with automatic retries.
* Validate a webhook with synchronous automatic retries.
*
* This is a Laravel-friendly facade helper kept for DX and backward compatibility.
* For asynchronous retry processing, prefer the ReceiveWebhook / RetryWebhook flow.
*
* @throws InvalidSignatureException
* @throws WebhookException
Expand All @@ -110,31 +117,33 @@ public function validateWithRetries(
string $event
): WebhookLog {
$webhookService = $this->resolveService($service);
$maxAttempts = $this->getRetryPolicyResolver()->resolve()->maxAttempts;
$retryPolicy = $this->getRetryPolicyResolver()->resolve();

if ($maxAttempts <= 0) {
if ($retryPolicy->maxAttempts <= 0) {
throw new WebhookException('Validation failed with no recorded exception.');
}

$delays = $this->getRetryPolicyResolver()->resolve()->delays;
$rawPayload = RawPayload::fromString($payload);
$externalId = $this->extractExternalId($webhookService, $rawPayload);

$lastLog = null;

for ($attempt = 0; $attempt < $maxAttempts; $attempt++) {
for ($attempt = 0; $attempt < $retryPolicy->maxAttempts; $attempt++) {
$lastLog = $this->validateAndRecord(
payload: $payload,
signature: $signature,
service: $webhookService,
event: $event,
attempt: $attempt,
externalId: $this->extractExternalId($webhookService, RawPayload::fromString($payload)),
externalId: $externalId,
);

if ($lastLog->status !== 'failed') {
return $lastLog;
}

if ($attempt < $maxAttempts - 1) {
$delay = $delays[$attempt] ?? 0;
if ($retryPolicy->shouldRetryAfter($attempt)) {
$delay = $retryPolicy->delayForAttempt($attempt) ?? 0;

if ($delay > 0) {
sleep($delay);
Expand All @@ -150,7 +159,7 @@ public function validateWithRetries(
/**
* Log a successful webhook.
*
* @deprecated Use validateAndLog() or the corresponding application use case.
* @deprecated Prefer validateAndLog() for validated webhooks or RecordWebhookLog for explicit audit writes.
*/
public function logSuccess(
string $service,
Expand All @@ -165,14 +174,16 @@ public function logSuccess(
valid: true,
payload: $payload,
attempt: $attempt,
externalId: null,
idempotencyKey: $idempotencyKey,
errorMessage: null,
));
}

/**
* Log a failed webhook.
*
* @deprecated Use validateAndLog() or the corresponding application use case.
* @deprecated Prefer validateAndLog() for validated webhooks or RecordWebhookLog for explicit audit writes.
*/
public function logFailure(
string $service,
Expand All @@ -188,6 +199,7 @@ public function logFailure(
valid: false,
payload: $payload,
attempt: $attempt,
externalId: null,
idempotencyKey: $idempotencyKey,
errorMessage: $errorMessage,
));
Expand Down Expand Up @@ -453,7 +465,7 @@ private function validateAndRecord(
): WebhookLog {
$webhookService = $this->resolveService($service);
$rawPayload = RawPayload::fromString($payload);
$secret = $this->getSecretResolver()->resolve($webhookService);
$secret = $this->getSecret($webhookService);

if ($secret === null || $secret === '') {
throw new WebhookException("No secret configured for service: {$webhookService->value}");
Expand Down
7 changes: 3 additions & 4 deletions src/Shared/Infrastructure/Laravel/Facades/Larawebhook.php
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,6 @@
* @method static bool validate(string $payload, Signature $signature, string|WebhookService $service)
* @method static WebhookLog validateAndLog(string $payload, Signature $signature, string|WebhookService $service, string $event)
* @method static WebhookLog validateWithRetries(string $payload, Signature $signature, string|WebhookService $service, string $event)
* Legacy helpers logSuccess() and logFailure() are deprecated; prefer validateAndLog() and application use cases.
* @method static WebhookLog logSuccess(string $service, string $event, array $payload, int $attempt = 0, ?string $idempotencyKey = null)
* @method static WebhookLog logFailure(string $service, string $event, array $payload, string $errorMessage, int $attempt = 0, ?string $idempotencyKey = null)
* @method static Collection logs()
Expand All @@ -25,12 +24,12 @@
* @method static bool canSendNotification(string $service, string $event)
* @method static bool sendNotificationIfNeeded(string $service, string $event)
* @method static bool notificationsEnabled()
* @method static array getNotificationChannels()
* @method static array<int, string> getNotificationChannels()
* @method static void clearCooldown(string $service, string $event)
* @method static ?string getSecret(string|WebhookService $service)
* @method static bool isServiceSupported(string $service)
* @method static array supportedServices()
* @method static array services()
* @method static array<int, string> supportedServices()
* @method static array<int, string> services()
* @method static ?WebhookService service(string $service)
*
* @see \Proxynth\Larawebhook\Shared\Application\Larawebhook
Expand Down