Laravel Webhook Server Laravel Package

Getting Started

Install the package via Composer, publish the config file, and configure your queue driver (avoid sync in production). Start dispatching webhooks with minimal code:

use Spatie\WebhookServer\WebhookCall;

WebhookCall::create()
   ->url('https://api.example.com/webhook')
   ->payload(['event' => 'order.created', 'order_id' => 123])
   ->useSecret(config('webhooks.shared_secret'))
   ->dispatch();

The DispatchingWebhookCallEvent fires on dispatch, and FinalWebhookCallFailedEvent on total failure—hook into these for monitoring.

Implementation Patterns

• Domain Events: Fire webhooks from domain events (e.g., OrderShipped, UserRegistered) using listeners or event subscribers.
• Reusability: Wrap webhook calls in service classes (e.g., WebhookSender) for consistent payloads, signing, and error handling.
• Environment-driven configs: Use environment-specific config overrides (e.g., WEBHOOK_BASE_URL) via config caching or runtime config (config()->set()).
• Retry strategy tuning: Override ExponentialBackoffStrategy for external system constraints—e.g., stricter limits for third-party APIs.
• Queue integration: Use dedicated webhook queues (e.g., webhooks) with Horizon workers to isolate retries and prevent blocking critical jobs.
• Testing: Stub HTTP calls with Laravel’s Http::fake() in tests; assert dispatched events and payloads.
• Signature verification: Ensure receiver apps verify Signature + Timestamp headers; use useTimestamp() to mitigate replay attacks.

Gotchas and Tips

• SQS delay limits: Avoid exponential backoffs exceeding 15 minutes between retries when using Amazon SQS (max delay = 15 mins). Consider custom backoff strategies or hybrid queues.
• Timestamp drift: If timing-sensitive systems (e.g., OAuth) verify Timestamp, ensure server clocks are NTP-synchronized.
• Timeouts: timeout_in_seconds applies per attempt—aggregate retries may exceed business SLAs. Adjust tries and timeout_in_seconds together.
• SSL verification: Disable only for dev/testing (verify_ssl => false); never in production. Provide custom CA via verifySsl($caPath) if needed.
• Mutual TLS caveats: Requires local OpenSSL support; verify cert/key paths exist and are readable by the queue worker (permissions issues are common).
• Custom signers: The calculateSignature payload must match what the receiver expects—e.g., JSON key order matters if non-normalized. Test signature generation against actual receivers.
• Error handling: Set throw_exception_on_failure => true in tests to catch failures early, but keep it false in prod to avoid cascading failures.
• Queue tag debugging: Use tags config to tag jobs (e.g., ['webhook', 'order_service']), then filter in Horizon for troubleshooting.
• Missing headers: Confirm receiving apps expect the configured signature_header_name (Signature) and timestamp_header_name (Timestamp). Mismatches cause validation failures.