Laravel Ohdear Webhooks Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require ohdearapp/laravel-ohdear-webhooks
   

   Publish the config file:

   php artisan vendor:publish --provider="OhDear\LaravelOhDearWebhooks\ServiceProvider" --tag="config"
   

2. Configure .env Add your Oh Dear API key and webhook secret:

   OHDEAR_API_KEY=your_api_key_here
   OHDEAR_WEBHOOK_SECRET=your_webhook_secret_here
   

3. Verify Webhook Endpoint Ensure your Laravel app’s routes/web.php includes:

   use OhDear\LaravelOhDearWebhooks\Facades\OhDearWebhook;
   
   Route::post('/ohdear-webhook', [OhDearWebhook::class, 'handle']);
   

4. First Use Case: Log Alerts Define a listener in app/Listeners/OhDearAlertListener.php:

   namespace App\Listeners;
   
   use OhDear\LaravelOhDearWebhooks\Events\AlertReceived;
   
   class OhDearAlertListener
   {
       public function handle(AlertReceived $event)
       {
           \Log::info('Oh Dear Alert:', [
               'id' => $event->alert->id,
               'type' => $event->alert->type,
               'message' => $event->alert->message,
           ]);
       }
   }
   

   Register the listener in EventServiceProvider:

   protected $listen = [
       AlertReceived::class => [
           OhDearAlertListener::class,
       ],
   ];
   

Implementation Patterns

Core Workflow: Handling Webhooks

1. Signature Verification The package automatically verifies the X-OhDear-Signature header against your OHDEAR_WEBHOOK_SECRET. No manual validation needed.

2. Event-Driven Architecture

   • Use AlertReceived for monitoring alerts (e.g., downtime, SSL expiry).
   • Use CheckUpdated for check status changes (e.g., "back online").
   • Extend with custom events by implementing OhDear\LaravelOhDearWebhooks\Contracts\WebhookEvent.

3. Integration with Laravel Queues Offload processing by dispatching events to queues:

   public function handle(AlertReceived $event)
   {
       dispatch(new ProcessOhDearAlert($event->alert))->onQueue('ohdear');
   }
   

4. Dynamic Routing Override the default route by binding a custom controller:

   Route::post('/custom-webhook', [CustomOhDearController::class, 'handle']);
   

Common Use Cases

Gotchas and Tips

Pitfalls

1. Secret Mismatch

   • Symptom: Webhook requests fail with 403 Forbidden.
   • Fix: Double-check OHDEAR_WEBHOOK_SECRET in .env and Oh Dear dashboard.
   • Debug: Enable OHDEAR_DEBUG=true to log signature verification steps.

2. Missing Events

   • Symptom: No events fired despite webhook hits.
   • Fix: Ensure the route is not blocked by middleware (e.g., auth or verified). Use:

     Route::post('/ohdear-webhook')->middleware('webhook:ohdear')->name('ohdear.webhook');
     

3. Rate Limiting

   • Oh Dear may throttle webhooks during outages. Implement exponential backoff in listeners:

     use Symfony\Component\RateLimiter\RateLimiter;
     
     $limiter = app(RateLimiter::class);
     if (!$limiter->consume('ohdear_alerts', 10, now()->addMinute())) {
         return; // Skip processing
     }
     

Tips

1. Custom Payload Handling Extend the OhDearWebhook facade to parse raw payloads:

   namespace OhDear\LaravelOhDearWebhooks\Facades;
   
   class OhDearWebhook extends \Illuminate\Support\Facades\Facade
   {
       public static function customPayload()
       {
           return request()->ohdear_payload ?? null;
       }
   }
   

2. Testing Webhooks Use Laravel’s Http test client to simulate webhooks:

   $response = $this->post('/ohdear-webhook', [], [
       'HTTP_X_OHDEAR_SIGNATURE' => 'valid_signature',
       'Accept' => 'application/json',
   ]);
   $response->assertOk();
   

3. Performance

   • Batch Processing: For high-volume checks, aggregate alerts in a queue worker:

     public function handle(AlertReceived $event)
     {
         AlertBatch::dispatch($event->alert)->onQueue('batch');
     }
     

   • Caching: Cache check metadata (e.g., check->last_checked) to avoid redundant DB writes.

4. Extension Points

   • Custom Validators: Implement OhDear\LaravelOhDearWebhooks\Contracts\WebhookValidator to add pre-processing logic.
   • Webhook Types: Support additional Oh Dear webhook types (e.g., maintenance) by extending the WebhookEvent class.

5. Configuration Quirks

   • Debug Mode: Enable OHDEAR_DEBUG=true to log raw payloads and signatures (useful for troubleshooting).
   • Environment-Specific Secrets: Use Laravel’s env() helper or config() to load secrets dynamically:

     config(['ohdear.secret' => env('OHDEAR_WEBHOOK_SECRET_' . app()->environment)]);