Weave Code
Laravel Ohdear Webhooks Laravel Package
ohdearapp/laravel-ohdear-webhooks
Handle Oh Dear webhooks in your Laravel app with automatic signature verification and configurable jobs or events dispatched for each webhook type. Just install, publish the config, set your signing secret, and register the route.
Laravel Oh Dear Webhooks lets your Laravel application receive and handle webhooks sent by Oh Dear. Out of the box it verifies the Oh Dear signature on every incoming request, so you can trust that each payload genuinely came from Oh Dear. Once a webhook is validated, the package dispatches the job or event you've mapped to that specific webhook type—leaving the actual handling logic entirely up to you.
Configuration is minimal: publish the config file, set your signing secret, map webhook events (such as uptimeCheckFailed or uptimeCheckRecovered) to jobs, and register the route with Route::ohDearWebhooks().
- Automatic signature verification for all incoming requests
- Map any Oh Dear webhook event to a job or event via config
- Simple config publishing with
signing_secretsupport - One-line route registration with
Route::ohDearWebhooks() - Auto-registered service provider—no manual setup
Frequently asked questions about Laravel Ohdear Webhooks
- How do I install and configure ohdearapp/laravel-ohdear-webhooks in a Laravel app?
- Run composer require ohdearapp/laravel-ohdear-webhooks; the service provider registers itself through auto-discovery. Publish the config with php artisan vendor:publish --provider="OhDear\LaravelWebhooks\OhDearWebhooksServiceProvider" --tag="config", then set the signing_secret key (usually via OH_DEAR_SIGNING_SECRET in your .env). Register the endpoint with Route::ohDearWebhooks('webhooks/ohdear'), add that URI to the $except array of VerifyCsrfToken, and point Oh Dear's webhook settings at the same URL.
- Why does my Oh Dear webhook endpoint return a 419 error?
- A 419 means Laravel's CSRF protection rejected the POST, because Oh Dear cannot send a CSRF token. Add the webhook URI to the $except array in app/Http/Middleware/VerifyCsrfToken.php. This is the single most common misconfiguration with this package, and it looks like an application error rather than a routing one.
- How does the package verify incoming Oh Dear webhook signatures?
- Every inbound request is checked against the signing_secret value in config/ohdear-webhooks.php before any job or event is dispatched. The comparison uses hash_equals so it is constant-time, a fix shipped in 1.0.1. If the secret does not match the one shown on Oh Dear's notification settings screen, requests are rejected, so keep the .env value in sync.
- How do I map an Oh Dear event type to a job or Laravel event?
- The published config contains a jobs array keyed by event type strings such as uptimeCheckFailed and uptimeCheckRecovered, with your job or event class as the value. When that event type arrives, the package dispatches the mapped queued job, or a Laravel event named ohdear-webhooks::<type>. The full list of event names is in Oh Dear's webhook documentation.
- Which Laravel versions does laravel-ohdear-webhooks support?
- The package relies on package auto-discovery, which is available from Laravel 5.5 onward. Because majors can drop older framework versions and the 2.0.0 changelog gives no upgrade guide, check the illuminate/support constraint in composer.json on Packagist before you commit. Confirm the current release against Packagist at decision time rather than trusting cached metadata.
- What data can I access from the OhDearWebhookCall object?
- The typed payload wrapper exposes payload, type(), monitor(), run(), and dateTime(), so handlers can branch on the event type without touching the raw request. Note that monitor() and run() return plain arrays and the contract carries no schema version. If Oh Dear renames an attribute, the failure surfaces as a null inside your handler rather than an exception at the boundary, so validate before use.
- Does the package retry, deduplicate, or store webhook payloads?
- No. That is a deliberate scope boundary: the package owns authentication, routing, deserialization, and dispatch, and nothing after that. Idempotency, audit logging, retry semantics, and alert routing are your application's responsibility. Plan for the fact that Oh Dear may deliver the same event more than once and design handlers accordingly.
- What happens if I mistype an event name or job class in the config?
- A mistyped job class fails loudly, thanks to the jobClassDoesNotExist handler added in 1.3.1. A mistyped event key fails silently: the webhook still returns 200 but no job or event is ever dispatched. There is no boot-time validation or type safety on that array, so for a monitoring integration you should test each configured event type before shipping.
- Is laravel-ohdear-webhooks actively maintained and safe for production?
- It is vendor-owned by Oh Dear and authored by Freek Van der Herten and Mattias Geniar, so there is a direct commercial incentive to keep it compatible with their own webhook API, which materially de-risks it. The caveats are real though: single vendor, single maintainer, roughly 23 stars and zero dependents, meaning no downstream community pressure testing releases. The 2.0.0 changelog reads only "v2 by @freekmurze" with no upgrade guide, so read the diff before bumping a major, and confirm CI and test status before adopting a security-adjacent component.
- How do I test Oh Dear webhooks without hitting my production app?
- Point the webhook URL in Oh Dear's notification settings at a local tunnel or staging endpoint, and send a test webhook from that screen. Because every request must carry a valid signature, any hand-crafted request needs to be signed with the same signing_secret your app is configured with. For automated tests, post to the route with a correctly signed payload and assert the mapped job or event was dispatched.
Weaver
How can I help you explore Laravel packages today?