Laravel Webhook Client Laravel Package

Product Decisions This Supports

• Webhook Integration Roadmap: Accelerates the timeline for integrating third-party webhook APIs (e.g., Stripe, GitHub, Slack, or custom SaaS platforms) by providing a standardized, Laravel-native solution. Eliminates the need to build custom middleware or validation logic for each webhook endpoint.
• Build vs. Buy: Buy—reduces development effort by ~80% for signature validation, payload storage, and async processing. Avoids reinventing wheel for security (HMAC/SHA-256) and scalability (queued jobs).
• Use Cases:
  • Event-Driven Architecture: Enables real-time updates (e.g., payment confirmations, user actions) without polling.
  • Auditability: Persists webhook payloads in a database for debugging/replayability (configurable retention via delete_after_days).
  • Multi-Tenant Webhooks: Supports distinct endpoints for different services (e.g., stripe-webhook, github-webhook) via the configs array in the config file.
  • Security Compliance: Mandates signature validation to prevent spoofing attacks (e.g., replay attacks, MITM).
  • Scalability: Offloads processing to queues (e.g., Redis, database) to handle high-volume webhooks without blocking HTTP responses.

When to Consider This Package

• Adopt When:
  • Your Laravel app needs to consume webhooks from external services (e.g., payment processors, Git providers, analytics tools).
  • You require signature verification (HMAC/SHA-256) to ensure payload integrity.
  • You want to store and replay webhook payloads for debugging or compliance (e.g., PCI DSS).
  • Your team lacks expertise in secure webhook handling or wants to avoid custom middleware.
  • You’re using Laravel and want to leverage its ecosystem (queues, events, middleware).
• Look Elsewhere If:
  • You need to send webhooks (use spatie/laravel-webhook-server instead).
  • Your webhooks use non-HMAC signatures (e.g., JWT, custom headers). Extend the SignatureValidator interface to support your scheme.
  • You require low-latency processing (e.g., real-time stock trading). Disable queuing and process synchronously (but risk slower HTTP responses).
  • Your infrastructure doesn’t support queues (e.g., shared hosting). Use the sync driver, but expect degraded performance.
  • You need advanced routing (e.g., path-based webhook separation). Combine with Laravel’s route model binding or middleware.
  • Your payloads exceed database limits (e.g., large files). Store payloads in S3/Blob storage and reference them in the webhook_calls table.

How to Pitch It (Stakeholders)

For Executives:

"This package lets us securely and scalably receive webhooks from third-party services—like Stripe for payments or GitHub for code updates—without building custom infrastructure. It handles security (signature verification), reliability (queued processing), and auditability (database storage) out of the box. For example, integrating Stripe’s webhooks could take days with custom code but hours with this package. It also future-proofs us for compliance needs (e.g., replaying transactions for audits). The cost? Zero—it’s open-source and maintained by a trusted Laravel vendor."

For Engineering:

*"This is a drop-in solution for webhook consumption in Laravel. Key benefits:

• Security: Validates HMAC-SHA256 signatures automatically (configurable).
• Scalability: Uses Laravel queues to process payloads asynchronously (no HTTP timeouts).
• Flexibility: Extendable for custom validation (SignatureValidator), filtering (WebhookProfile), or responses (RespondsToWebhook).
• Debugging: Stores all payloads in a webhook_calls table with metadata (headers, exceptions).
• Multi-Service: Supports multiple webhook endpoints (e.g., one for Stripe, one for Slack) via the configs array.

Tradeoffs:

• Requires a database table for storage (but you can customize the model).
• Assumes HMAC signatures (but you can implement custom validators).
• Needs a queue driver (but falls back to sync if misconfigured).

Implementation:

1. Install via Composer: composer require spatie/laravel-webhook-client.
2. Publish config/migrations: php artisan vendor:publish --provider="Spatie\WebhookClient\WebhookClientServiceProvider".
3. Route webhooks: Route::webhooks('stripe-webhook').
4. Extend ProcessWebhookJob to handle payloads.

Example Use Case: For Stripe webhooks, we’d:

• Set signing_secret to Stripe’s webhook secret.
• Extend ProcessWebhookJob to parse Stripe events (e.g., payment_intent.succeeded).
• Queue the job to avoid slow HTTP responses.

This cuts our webhook integration time by 70% while adding security and observability."*