# proxynth/larawebhook architecture

> Architecture diagram of the GitHub repository proxynth/larawebhook, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/proxynth/larawebhook
- Repository: https://github.com/proxynth/larawebhook

## Overview

LaraWebhook is a Laravel package for receiving and validating provider webhooks, preventing duplicate processing, recording audit logs, and supporting retries, replay, notifications, and log review. The main flow is an incoming request through the receive use case, which coordinates parsing, validation, idempotency checks, and audit recording; Laravel adapters provide persistence and HTTP access. The README documents provider support, payload privacy modes, retention, dashboard/API access, retry, and replay. Some subsystems are represented by their exact source directories because their implementation was not excerpted.

Main entry points: [`src/Ingestion/Application/UseCases/ReceiveWebhook.php`](https://github.com/proxynth/larawebhook/blob/main/src/Ingestion/Application/UseCases/ReceiveWebhook.php) (Receive webhook), [`src/Audit/Infrastructure/Logging/WebhookLogger.php`](https://github.com/proxynth/larawebhook/blob/main/src/Audit/Infrastructure/Logging/WebhookLogger.php) (Webhook logger), [`src/Shared/Infrastructure/Laravel/Providers/LarawebhookServiceProvider.php`](https://github.com/proxynth/larawebhook/blob/main/src/Shared/Infrastructure/Laravel/Providers/LarawebhookServiceProvider.php) (Laravel service provider), [`src/Processing/Application/UseCases/RetryWebhook.php`](https://github.com/proxynth/larawebhook/blob/main/src/Processing/Application/UseCases/RetryWebhook.php) (Retry use case)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Webhook ingestion"]
  node_receive["Receive webhook<br/>[ReceiveWebhook.php]"]
  node_validate["Validate webhook"]
  node_provider_validation["Provider validators"]
  node_payload_parsing["Provider parsers"]
end

subgraph group_processing["Processing and recovery"]
  node_webhook_event["Webhook event state<br/>[WebhookEvent.php]"]
  node_idempotency["Idempotency and deduplication"]
  node_processed_store[("Processed event store")]
  node_retry["Retry use case<br/>[RetryWebhook.php]"]
  node_retry_job["Retry job"]
  node_replay["Replay use case<br/>[ReplayWebhook.php]"]
end

subgraph group_audit["Audit and privacy"]
  node_audit_record["Record webhook log"]
  node_audit_logger["Webhook logger<br/>[WebhookLogger.php]"]
  node_payload_storage["Payload privacy"]
  node_audit_store[("Webhook log store<br/>[WebhookLog.php]")]
  node_log_queries["Log queries"]
  node_notifications["Failure notifications"]
  node_retention["Log retention"]
end

subgraph group_laravel["Laravel integration"]
  node_dashboard["Dashboard"]
  node_log_api["Log and replay API"]
  node_service_provider["Laravel service provider"]
end

subgraph group_shared["Shared domain"]
  node_service_ids["Service identifiers<br/>[WebhookService.php]"]
end

node_sender(("Webhook sender"))

node_sender -->|"sends request"| node_receive
node_receive -->|"validates"| node_validate
node_receive -->|"resolves parser"| node_payload_parsing
node_receive -->|"resolves key"| node_idempotency
node_receive -->|"creates event"| node_webhook_event
node_receive -->|"records processing"| node_processed_store
node_receive -->|"records audit log"| node_audit_record
node_validate -.->|"validates signature"| node_provider_validation
node_service_provider -->|"registers validators"| node_provider_validation
node_service_provider -->|"registers parsers"| node_payload_parsing
node_service_ids -.->|"selects provider"| node_provider_validation
node_retry -->|"revalidates"| node_validate
node_retry -->|"records attempt"| node_audit_record
node_retry_job -.->|"dispatches retry"| node_retry
node_replay -.->|"replays event"| node_webhook_event
node_log_api -->|"requests replay"| node_replay
node_audit_record -->|"records through"| node_audit_logger
node_audit_logger -->|"resolves payload"| node_payload_storage
node_audit_logger -.->|"persists logs"| node_audit_store
node_dashboard -.->|"reads logs"| node_log_queries
node_log_api -->|"queries logs"| node_log_queries
node_retention -.->|"prunes logs"| node_audit_store
node_notifications -.->|"alerts on failures"| node_audit_logger
node_service_provider -->|"registers logger"| node_audit_logger
node_service_provider -->|"registers notifications"| node_notifications

click node_receive "https://github.com/proxynth/larawebhook/blob/main/src/Ingestion/Application/UseCases/ReceiveWebhook.php"
click node_validate "https://github.com/proxynth/larawebhook/blob/main/src/Ingestion/Application/UseCases/ValidateWebhook.php"
click node_provider_validation "https://github.com/proxynth/larawebhook/tree/main/src/Ingestion/Infrastructure/Validation"
click node_payload_parsing "https://github.com/proxynth/larawebhook/tree/main/src/Ingestion/Infrastructure/Parsing"
click node_service_ids "https://github.com/proxynth/larawebhook/blob/main/src/Shared/Domain/Enums/WebhookService.php"
click node_webhook_event "https://github.com/proxynth/larawebhook/blob/main/src/Processing/Domain/Entities/WebhookEvent.php"
click node_idempotency "https://github.com/proxynth/larawebhook/blob/main/src/Processing/Infrastructure/Idempotency/DefaultIdempotencyResolver.php"
click node_processed_store "https://github.com/proxynth/larawebhook/blob/main/src/Processing/Infrastructure/Persistence/EloquentProcessedWebhookRecorder.php"
click node_retry "https://github.com/proxynth/larawebhook/blob/main/src/Processing/Application/UseCases/RetryWebhook.php"
click node_retry_job "https://github.com/proxynth/larawebhook/blob/main/src/Processing/Infrastructure/Laravel/Jobs/RetryWebhookJob.php"
click node_replay "https://github.com/proxynth/larawebhook/blob/main/src/Processing/Application/UseCases/ReplayWebhook.php"
click node_audit_record "https://github.com/proxynth/larawebhook/blob/main/src/Audit/Application/Commands/RecordWebhookLogCommand.php"
click node_audit_logger "https://github.com/proxynth/larawebhook/blob/main/src/Audit/Infrastructure/Logging/WebhookLogger.php"
click node_payload_storage "https://github.com/proxynth/larawebhook/blob/main/src/Audit/Infrastructure/Payload/PayloadStorageResolver.php"
click node_audit_store "https://github.com/proxynth/larawebhook/blob/main/src/Audit/Infrastructure/Laravel/Persistence/Models/WebhookLog.php"
click node_log_queries "https://github.com/proxynth/larawebhook/blob/main/src/Shared/Infrastructure/Laravel/Queries/WebhookLogQueries.php"
click node_dashboard "https://github.com/proxynth/larawebhook/blob/main/src/Audit/Infrastructure/Laravel/Http/Controllers/DashboardController.php"
click node_log_api "https://github.com/proxynth/larawebhook/blob/main/src/Audit/Infrastructure/Laravel/Http/Controllers/WebhookLogController.php"
click node_notifications "https://github.com/proxynth/larawebhook/blob/main/src/Audit/Infrastructure/Laravel/Notifications/NotificationSender.php"
click node_retention "https://github.com/proxynth/larawebhook/blob/main/src/Audit/Application/UseCases/PruneWebhookLogs.php"
click node_service_provider "https://github.com/proxynth/larawebhook/blob/main/src/Shared/Infrastructure/Laravel/Providers/LarawebhookServiceProvider.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_receive,node_validate,node_provider_validation,node_payload_parsing toneBlue
class node_webhook_event,node_idempotency,node_processed_store,node_retry,node_retry_job,node_replay toneAmber
class node_audit_record,node_audit_logger,node_payload_storage,node_audit_store,node_log_queries,node_notifications,node_retention,node_sender toneMint
class node_dashboard,node_log_api,node_service_provider toneRose
class node_service_ids toneIndigo
```

## Components

### Webhook ingestion

- [Receive webhook](https://github.com/proxynth/larawebhook/blob/main/src/Ingestion/Application/UseCases/ReceiveWebhook.php): `src/Ingestion/Application/UseCases/ReceiveWebhook.php`
- [Validate webhook](https://github.com/proxynth/larawebhook/blob/main/src/Ingestion/Application/UseCases/ValidateWebhook.php): `src/Ingestion/Application/UseCases/ValidateWebhook.php`
- [Provider validators](https://github.com/proxynth/larawebhook/tree/main/src/Ingestion/Infrastructure/Validation): `src/Ingestion/Infrastructure/Validation`
- [Provider parsers](https://github.com/proxynth/larawebhook/tree/main/src/Ingestion/Infrastructure/Parsing): `src/Ingestion/Infrastructure/Parsing`

### Processing and recovery

- [Webhook event state](https://github.com/proxynth/larawebhook/blob/main/src/Processing/Domain/Entities/WebhookEvent.php): `src/Processing/Domain/Entities/WebhookEvent.php`
- [Idempotency and deduplication](https://github.com/proxynth/larawebhook/blob/main/src/Processing/Infrastructure/Idempotency/DefaultIdempotencyResolver.php): `src/Processing/Infrastructure/Idempotency/DefaultIdempotencyResolver.php`
- [Processed event store](https://github.com/proxynth/larawebhook/blob/main/src/Processing/Infrastructure/Persistence/EloquentProcessedWebhookRecorder.php): `src/Processing/Infrastructure/Persistence/EloquentProcessedWebhookRecorder.php`
- [Retry use case](https://github.com/proxynth/larawebhook/blob/main/src/Processing/Application/UseCases/RetryWebhook.php): `src/Processing/Application/UseCases/RetryWebhook.php`
- [Retry job](https://github.com/proxynth/larawebhook/blob/main/src/Processing/Infrastructure/Laravel/Jobs/RetryWebhookJob.php): `src/Processing/Infrastructure/Laravel/Jobs/RetryWebhookJob.php`
- [Replay use case](https://github.com/proxynth/larawebhook/blob/main/src/Processing/Application/UseCases/ReplayWebhook.php): `src/Processing/Application/UseCases/ReplayWebhook.php`

### Audit and privacy

- [Record webhook log](https://github.com/proxynth/larawebhook/blob/main/src/Audit/Application/Commands/RecordWebhookLogCommand.php): `src/Audit/Application/Commands/RecordWebhookLogCommand.php`
- [Webhook logger](https://github.com/proxynth/larawebhook/blob/main/src/Audit/Infrastructure/Logging/WebhookLogger.php): `src/Audit/Infrastructure/Logging/WebhookLogger.php`
- [Payload privacy](https://github.com/proxynth/larawebhook/blob/main/src/Audit/Infrastructure/Payload/PayloadStorageResolver.php): `src/Audit/Infrastructure/Payload/PayloadStorageResolver.php`
- [Webhook log store](https://github.com/proxynth/larawebhook/blob/main/src/Audit/Infrastructure/Laravel/Persistence/Models/WebhookLog.php): `src/Audit/Infrastructure/Laravel/Persistence/Models/WebhookLog.php`
- [Log queries](https://github.com/proxynth/larawebhook/blob/main/src/Shared/Infrastructure/Laravel/Queries/WebhookLogQueries.php): `src/Shared/Infrastructure/Laravel/Queries/WebhookLogQueries.php`
- [Failure notifications](https://github.com/proxynth/larawebhook/blob/main/src/Audit/Infrastructure/Laravel/Notifications/NotificationSender.php): `src/Audit/Infrastructure/Laravel/Notifications/NotificationSender.php`
- [Log retention](https://github.com/proxynth/larawebhook/blob/main/src/Audit/Application/UseCases/PruneWebhookLogs.php): `src/Audit/Application/UseCases/PruneWebhookLogs.php`

### Laravel integration

- [Dashboard](https://github.com/proxynth/larawebhook/blob/main/src/Audit/Infrastructure/Laravel/Http/Controllers/DashboardController.php): `src/Audit/Infrastructure/Laravel/Http/Controllers/DashboardController.php`
- [Log and replay API](https://github.com/proxynth/larawebhook/blob/main/src/Audit/Infrastructure/Laravel/Http/Controllers/WebhookLogController.php): `src/Audit/Infrastructure/Laravel/Http/Controllers/WebhookLogController.php`
- [Laravel service provider](https://github.com/proxynth/larawebhook/blob/main/src/Shared/Infrastructure/Laravel/Providers/LarawebhookServiceProvider.php): `src/Shared/Infrastructure/Laravel/Providers/LarawebhookServiceProvider.php`

### Shared domain

- [Service identifiers](https://github.com/proxynth/larawebhook/blob/main/src/Shared/Domain/Enums/WebhookService.php): `src/Shared/Domain/Enums/WebhookService.php`

### Other components

- **Webhook sender**

## Connections

- Webhook sender → Receive webhook: sends request (evidence: `README.md`)
- Receive webhook → Validate webhook: validates (evidence: `src/Ingestion/Application/UseCases/ReceiveWebhook.php`)
- Receive webhook → Provider parsers: resolves parser (evidence: `src/Ingestion/Application/UseCases/ReceiveWebhook.php`)
- Receive webhook → Idempotency and deduplication: resolves key (evidence: `src/Ingestion/Application/UseCases/ReceiveWebhook.php`)
- Receive webhook → Webhook event state: creates event (evidence: `src/Ingestion/Application/UseCases/ReceiveWebhook.php`)
- Receive webhook → Processed event store: records processing (evidence: `src/Ingestion/Application/UseCases/ReceiveWebhook.php`)
- Receive webhook → Record webhook log: records audit log (evidence: `src/Ingestion/Application/UseCases/ReceiveWebhook.php`)
- Validate webhook → Provider validators: validates signature
- Laravel service provider → Provider validators: registers validators (evidence: `src/Shared/Infrastructure/Laravel/Providers/LarawebhookServiceProvider.php`)
- Laravel service provider → Provider parsers: registers parsers (evidence: `src/Shared/Infrastructure/Laravel/Providers/LarawebhookServiceProvider.php`)
- Service identifiers → Provider validators: selects provider (evidence: `src/Ingestion/Infrastructure/Validation/WebhookValidatorFactory.php`)
- Retry use case → Validate webhook: revalidates (evidence: `src/Processing/Application/UseCases/RetryWebhook.php`)
- Retry use case → Record webhook log: records attempt (evidence: `src/Processing/Application/UseCases/RetryWebhook.php`)
- Retry job → Retry use case: dispatches retry
- Replay use case → Webhook event state: replays event
- Log and replay API → Replay use case: requests replay (evidence: `src/Audit/Infrastructure/Laravel/Http/Controllers/WebhookLogController.php`)
- Record webhook log → Webhook logger: records through
- Webhook logger → Payload privacy: resolves payload (evidence: `src/Shared/Infrastructure/Laravel/Providers/LarawebhookServiceProvider.php`)
- Webhook logger → Webhook log store: persists logs
- Dashboard → Log queries: reads logs
- Log and replay API → Log queries: queries logs (evidence: `src/Audit/Infrastructure/Laravel/Http/Controllers/WebhookLogController.php`)
- Log retention → Webhook log store: prunes logs
- Failure notifications → Webhook logger: alerts on failures
- Laravel service provider → Webhook logger: registers logger (evidence: `src/Shared/Infrastructure/Laravel/Providers/LarawebhookServiceProvider.php`)
- Laravel service provider → Failure notifications: registers notifications (evidence: `src/Shared/Infrastructure/Laravel/Providers/LarawebhookServiceProvider.php`)
