Refactor to Spatie webhook client

[jordanpartridge]

Summary

• Refactor webhook handling to use spatie/laravel-webhook-client package
• Replace custom WebhookController with Spatie's webhook infrastructure
• Add HMAC signature validation support via GateSignatureValidator
• Maintain 100% test coverage with new unit tests for signature validation

Changes

• New Package: Added spatie/laravel-webhook-client v3.4
• New Classes:
  • App\Webhooks\GateSignatureValidator - HMAC-SHA256 signature verification
  • App\Webhooks\GateWebhookProfile - Payload validation (required fields, verdict enum)
  • App\Webhooks\ProcessGateWebhookJob - Fires CertificationCompleted Verbs event
• Config: config/webhook-client.php with gate endpoint configuration
• Migration: Creates webhook_calls table for webhook storage
• Removed: Old WebhookController and GateWebhookRequest classes

Test plan

• All existing webhook tests pass with updated assertions
• New unit tests for GateSignatureValidator (4 test cases)
• 100% code coverage maintained (19 tests, 38 assertions)
• Valid payloads are stored in webhook_calls and fire Verbs events
• Invalid payloads are silently rejected (not stored/processed)

Summary by CodeRabbit

• New Features
  • Webhook endpoints now require cryptographic signature validation for all incoming requests to ensure authenticity and security
  • All webhook calls are persisted to a database for comprehensive audit trails, tracking, and debugging purposes
  • Enhanced payload validation has been implemented to ensure only webhooks with all required data fields are processed
  • Webhook response format has been updated

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

This pull request replaces a custom webhook handler with the Spatie WebhookClient library. The changes remove the existing WebhookController and GateWebhookRequest classes, introduce Spatie-based signature validation and webhook processing components, add a configuration file for webhook handling, create a database migration for webhook storage, and update routes and tests accordingly.

Changes

Cohort / File(s)	Summary
Removed webhook controller app/Http/Controllers/WebhookController.php, app/Http/Requests/GateWebhookRequest.php	Deleted custom webhook handler and its request validation class; logic migrated to Spatie webhook-client integration.
Spatie webhook components app/Webhooks/GateSignatureValidator.php, app/Webhooks/GateWebhookProfile.php, app/Webhooks/ProcessGateWebhookJob.php	Added three new classes: GateSignatureValidator (HMAC-SHA256 signature validation), GateWebhookProfile (payload structure validation), and ProcessGateWebhookJob (webhook event dispatch handler).
Webhook configuration config/webhook-client.php	New configuration file defining gate webhook settings: signing secret source, signature header name, validator/profile/job classes, header storage, and cleanup schedule.
Database migration database/migrations/2025_12_15_045715_create_webhook_calls_table.php	New migration creating webhook_calls table with id, name, url, headers, payload, exception, and timestamps columns.
Dependencies and routing composer.json, routes/api.php	Added spatie/laravel-webhook-client (^3.4) dependency; replaced explicit controller route with Route::webhooks facade method.
Tests tests/Feature/WebhookGateTest.php, tests/Unit/GateSignatureValidatorTest.php	Updated feature tests to expect webhook storage in database and event dispatch via new system; added unit tests for signature validation scenarios.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Router as API Router
    participant SignatureValidator as GateSignatureValidator
    participant WebhookProfile as GateWebhookProfile
    participant ProcessJob as ProcessGateWebhookJob
    participant Database as DB (webhook_calls)
    participant Event as CertificationCompleted Event

    Client->>Router: POST /api/webhooks/gate<br/>(with signature header)
    Router->>SignatureValidator: isValid(request, config)
    alt Signature invalid
        SignatureValidator-->>Router: false
        Router-->>Client: HTTP 403
    else Signature valid
        SignatureValidator-->>Router: true
        Router->>WebhookProfile: shouldProcess(request)
        alt Payload invalid
            WebhookProfile-->>Router: false
            Router-->>Client: HTTP 400
        else Payload valid
            WebhookProfile-->>Router: true
            Router->>Database: Store webhook_calls record
            Database-->>Router: ✓ Stored
            Router->>ProcessJob: dispatch(webhook)
            ProcessJob->>Event: fire CertificationCompleted<br/>(repository, sha, verdict, ...)
            Event-->>ProcessJob: ✓ Dispatched
            ProcessJob-->>Router: ✓ Complete
            Router-->>Client: HTTP 202
        end
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

• Signature validation logic in GateSignatureValidator: verify HMAC-SHA256 implementation and hash_equals usage for timing-safe comparison
• Payload validation rules in GateWebhookProfile: ensure verdict enum and required field checks are correct
• Job payload mapping in ProcessGateWebhookJob: confirm all fields are correctly extracted and mapped to CertificationCompleted event parameters
• Configuration correctness: verify config/webhook-client.php aligns with Spatie library expectations and environment variable references
• Migration compatibility: ensure webhook_calls table schema matches Spatie's expected structure
• Test coverage: validate that feature and unit tests adequately cover new webhook flow and edge cases

Possibly related PRs

• Add webhook endpoint for gate certification intake #1: Introduced the original WebhookController and GateWebhookRequest classes that this PR replaces with Spatie webhook-client integration.

Poem

🐰 A hop, a skip, from controllers old—
Spatie's webhooks now take hold!
Signatures dance, profiles align,
Database stores each line so fine.
Jobs dispatch with grace sublime! ✨

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/spatie-webhook-client

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0ebabc6 and 4b98d4f.

⛔ Files ignored due to path filters (1)

• composer.lock is excluded by !**/*.lock

📒 Files selected for processing (11)

• app/Http/Controllers/WebhookController.php (0 hunks)
• app/Http/Requests/GateWebhookRequest.php (0 hunks)
• app/Webhooks/GateSignatureValidator.php (1 hunks)
• app/Webhooks/GateWebhookProfile.php (1 hunks)
• app/Webhooks/ProcessGateWebhookJob.php (1 hunks)
• composer.json (1 hunks)
• config/webhook-client.php (1 hunks)
• database/migrations/2025_12_15_045715_create_webhook_calls_table.php (1 hunks)
• routes/api.php (1 hunks)
• tests/Feature/WebhookGateTest.php (4 hunks)
• tests/Unit/GateSignatureValidatorTest.php (1 hunks)

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}