Laravel Sns Events Laravel Package

Getting Started

Laravel SNS Events 7.2.0 is primarily a platform-compatibility release: it adds Laravel 10.x and PHP 8.2 support while dropping Laravel 8.x and PHP 8.0. There are no obvious new day-to-day features in the release notes, so treat 7.2.0 as an upgrade gate rather than a feature release.

First steps:

1. Confirm your app is on a supported stack: Laravel 9.x/10.x and PHP 8.1/8.2. If you are still on Laravel 8 or PHP 8.0, upgrade Laravel/PHP before adopting 7.2.0.
2. Install or upgrade with Composer and check the resolved constraints:

   composer require renoki-co/laravel-sns-events:^7.2
   

3. Publish the package config if you have not already:

   php artisan vendor:publish --provider="RenokiCo\LaravelSnsEvents\LaravelSnsEventsServiceProvider"
   

4. Review the package README and published config first, especially route prefix/middleware, topic ARN, and signature-verification settings.
5. Configure an AWS SNS topic to POST to the package webhook route, then subscribe the endpoint.
6. Register a listener for the package’s SNS notification event and start by queueing a job rather than doing work inline.

First practical use case: receive SNS notifications from AWS, validate the SNS envelope, acknowledge quickly, and dispatch a Laravel job that maps the SNS Message payload into your own domain event or workflow.

Implementation Patterns

• Webhook as ingress only: Let the package route and validate the SNS request, then enqueue a job. Return a 2xx quickly so SNS does not retry due to slow application work.
• Handle SNS message types explicitly: Expect SubscriptionConfirmation, Notification, and potentially UnsubscribeConfirmation. Confirm subscriptions only after validating the topic ARN and signature-related fields.
• Map the SNS envelope to domain events: SNS wraps your payload in an envelope. The Message field is often a JSON string, so decode it deliberately and validate its shape before dispatching domain events.
• Deduplicate by MessageId: SNS delivery is at-least-once. Store processed MessageId values or use an idempotency key before running side effects.
• Queue listeners: Implement ShouldQueue on listeners or dispatch jobs from the listener. This keeps the HTTP response fast and gives you retries/backoff control in Laravel.
• Route by topic or message type: If one endpoint receives multiple SNS topics, inspect TopicArn and/or envelope metadata and route to different jobs/handlers.
• Keep signature verification on outside local testing: Use the package’s verification middleware/config in staging and production. Disable it only for local fixtures or controlled tests.
• Test with realistic SNS payloads: Use AWS SNS console deliveries, ngrok for public callbacks, or stored SNS request fixtures. Assert subscription confirmation, notification handling, duplicate delivery, and malformed payload behavior.
• Operational integration: Alert on webhook 5xx rates, queue failures, and signature-verification failures. These usually indicate misconfigured topic ARNs, proxy/body issues, or certificate-fetch problems.

Gotchas and Tips

• Breaking upgrade constraints: 7.2.0 drops Laravel 8.x and PHP 8.0. Update CI matrices, Docker images, composer.json platform constraints, and deployment runtimes before upgrading. Laravel 10/PHP 8.2 support is the main reason to move.
• No feature windfall: Do not expect new runtime behavior from 7.2.0. Plan it as a compatibility upgrade and regression-test existing webhook flows.
• Raw request body matters: SNS signature verification depends on the exact request body. Middleware that parses, normalizes, or re-encodes JSON can break verification.
• CSRF and middleware: The SNS route must not be blocked by CSRF. Prefer API-style middleware or explicitly exclude the webhook route from CSRF in web routes.
• Proxy and URL issues: Behind load balancers, ensure scheme/host forwarding is correct. Signature validation and subscription confirmation can fail if the application sees the wrong URL context.
• Subscription confirmation: A topic will not deliver notifications until the subscription is confirmed. Make sure the confirmation path is reachable and that SubscribeURL is validated before calling it.
• Topic ARN mismatch: Keep AWS_SNS_TOPIC_ARN/config values aligned per environment. A wrong ARN is a common cause of rejected or ignored messages.
• Config cache: After changing SNS env/config values, run php artisan config:clear or rebuild config cache in deploy.
• Certificate fetching: Signature verification may require outbound HTTPS access to AWS SNS certificate URLs. Firewalled environments can fail verification even when payloads look correct.
• SNS retries and duplicates: Timeouts, 5xx responses, and slow listeners cause retries. Keep the webhook fast, idempotent, and observable.
• Queue serialization: If you pass the whole SNS event into a queued job, ensure it is serializable and does not carry non-serializable request objects.
• Local signature verification: Disabling verification locally is useful, but make it impossible to disable accidentally in production via environment defaults.
• Extension points: Use the published config, route middleware, listener registration, and package event classes as the main customization points. If you need custom signature handling or payload mapping, keep it in your own listener/job layer rather than forking the package.