README

Laravel integration for federicozardi/eventing.

Provides a prebuilt webhook endpoint for EventBridge HTTP targets:

• HMAC authentication (X-Eventing-Timestamp, X-Eventing-Signature)
• JSON envelope parsing + validation
• Idempotency via DynamoDB inbox (dedupe on consumer + eventId)
• Handler dispatch by eventType

V1 processing is sync (as agreed). EventBridge retry policy handles transient failures.

Install

composer require federicozardi/eventing-laravel
php artisan vendor:publish --tag=config --provider="Amevista\\EventingLaravel\\Providers\\EventingServiceProvider"

Configuration

config/eventing.php:

• webhook.path (default: /api/events/webhook)
• webhook.secret (EVENTING_WEBHOOK_SECRET)
• consumer_name (EVENTING_CONSUMER_NAME)
• inbox.table (EVENTING_INBOX_TABLE)
• event_store.disable_concurrency_check (EVENTING_DISABLE_CONCURRENCY_CHECK, default: true)
• handlers[eventType] => HandlerClass

Env vars (typical):

EVENTING_WEBHOOK_SECRET=supersecret
EVENTING_CONSUMER_NAME=payment-service
EVENTING_INBOX_TABLE=eventing_inbox
EVENTING_DISABLE_CONCURRENCY_CHECK=true
AWS_DEFAULT_REGION=eu-west-3

Handlers

Create a handler implementing Amevista\\Eventing\\Contracts\\EventHandlerInterface:

use Amevista\\Eventing\\Contracts\\EventHandlerInterface;
use Amevista\\Eventing\\Envelope\\EventEnvelope;

final class OrderCreatedHandler implements EventHandlerInterface
{
    public function handle(EventEnvelope $event): void
    {
        // ...
    }
}

Map it in config:

'handlers' => [
  'order.created.v1' => \\App\\EventHandlers\\OrderCreatedHandler::class,
],

IaC notes (EventBridge → ALB Ingress)

This package assumes your IaC creates:

• EventBridge rule(s) matching detail-type / source
• HTTP target pointing to your ALB ingress URL + path
• Retry policy and (optionally) DLQ
• Secret management for EVENTING_WEBHOOK_SECRET (Kubernetes Secret)

With ALB Ingress, do not rely on static IP allowlists as primary authentication; use HMAC.

IAM notes (consumer)

This package performs inbox dedupe (DynamoDB PutItem) before dispatching handlers.

If EVENTING_DISABLE_CONCURRENCY_CHECK=true (default), the event store may also read the event store HEAD (dynamodb:GetItem) to append events best-effort.

Minimal DynamoDB permissions typically include:

• Inbox table: dynamodb:PutItem
• Event store table:
  • transactional writes: dynamodb:PutItem, dynamodb:UpdateItem, dynamodb:ConditionCheckItem
  • reads: dynamodb:GetItem (for HEAD when concurrency checks are disabled), dynamodb:Query (for loads)

Monorepo development note

In this monorepo the composer.json uses a path repository to resolve federicozardi/eventing locally. When you extract to separate repositories and tag releases, you should remove that block.