Laravel Ohdear Webhooks Laravel Package

Technical Evaluation

Architecture fit

The package is a thin inbound adapter, not a platform component. Its entire surface area is four things:

• A service provider that auto-registers and publishes config/ohdear-webhooks.php.
• A route macro — Route::ohDearWebhooks('...') — binding a POST endpoint to a package controller.
• Signature verification on every request using the shared signing_secret, compared with hash_equals (constant-time; fixed in 1.0.1).
• A dispatch layer mapping an Oh Dear event type (uptimeCheckFailed, uptimeCheckRecovered, …) to either a queued job from the jobs config array, or a Laravel event named ohdear-webhooks::<type>.

Payload access is deliberately loose: OhDearWebhookCall exposes payload (array), type(), monitor(), run(), dateTime(). The package explicitly refuses to own what happens after validation — a correct and healthy scope boundary, and the natural fault line between "package responsibility" and "our responsibility" in any design review.

For a standard Laravel app, this is the right shape: no new middleware stack, no persistence layer, no infrastructure. It is a ~200-line convenience wrapper. A TPM should frame the decision as buy-vs-build for a commodity, not as an architectural commitment.

Integration feasibility

Low effort, high predictability. Composer install, publish config, register the route, exclude the route from VerifyCsrfToken, implement one or more ShouldQueue jobs. A competent Laravel engineer completes a first working webhook in under a day, including the queue wiring.

The genuine work is downstream and sits entirely on our side: idempotency, alert routing, escalation policy, and observability. The package gives us nothing there, by design.

Technical risk

Key questions

1. What is the exact breaking-change list between 1.4.4 and 2.0.1, and which of our event types does it touch?
2. Which Oh Dear event types are in scope for us, and what is the authoritative source of truth for that list?
3. What is Oh Dear's retry policy and window on non-2xx responses, and does it guarantee at-least-once delivery?
4. Does the package verify the signature over the raw request body (correct) or a re-serialized payload (fragile)?
5. Who owns the OH_DEAR_SIGNING_SECRET rotation runbook?
6. Do we need Oh Dear at all for this signal, or do we already ingest uptime state elsewhere?

Integration Approach

Stack fit

Laravel-native, conventional, no opinions imposed beyond the route macro. Changelog evidences a maintained compatibility ladder: Laravel 5.6 through 11 tracked release-by-release, PHP 8 permitted from 1.4.1. Confirm the 2.x support matrix against composer.json rather than inferring it — 2.0.0 postdates the L11 support in 1.4.4 and likely targets newer framework/PHP baselines.

Migration path

Two distinct migrations, and they should not be conflated:

• From nothing — greenfield endpoint. Trivial; treat as configuration, not a project.
• From 1.x to 2.x — read the diff first, pin ^1.4 until the diff is understood, then bump in a branch with the full webhook test suite run. Given the changelog gives no migration guidance, budget a half-day of engineering due diligence before the bump, not after.

Compatibility

Three concrete coupling points: the CSRF $except array; queue configuration (the package docs strongly recommend queueable jobs/listeners — treat this as mandatory, not advisory); and Oh Dear's own webhook settings screen, which must point at our route and hold the same secret we configure.

Sequencing

1. Inventory the Oh Dear event types we actually act on; write them down as our own list of record.
2. Register the signing secret in the secret manager, not .env in the repo.
3. Install, publish config, register route macro, add CSRF exclusion — deploy to staging.
4. Implement jobs/listeners as ShouldQueue, each mapping to an internal domain event rather than raw payload handling.
5. Add a dedupe store keyed on type + monitor id + dateTime().
6. Add a config-validation test asserting every jobs key maps to an existing, queueable class.
7. Point Oh Dear at staging, fire a real test event, verify end-to-end including queue and alert delivery.
8. Cut over production URL; leave the old endpoint (if any) live for a soak period.

Step 4 matters most strategically: wrapping the package's dispatch in our own domain events keeps the vendor package at arm's length and makes it replaceable in a day.

Operational Impact

Maintenance

Low code surface, moderate coupling surface. Ongoing work is not patching this package — it is tracking two moving targets in parallel: package releases (a handful per year, currently paced to Laravel majors) and Oh Dear's webhook event catalog (which we have already seen change once). Realistic envelope: a few hours per quarter, plus a re-verification whenever we upgrade Laravel.

Support

MIT, community-supported, no SLA. Escalation path is the repo's issue tracker; security disclosures go to [email protected]. The mitigating factor is that the maintainers are the vendor — this package exists because Oh Dear needs it to work. Combined with the tiny surface, fork-and-own is a credible fallback, which materially lowers the vendor risk relative to the 23-star signal.

Scaling

Not a throughput concern. Volume is bounded by monitors × check frequency × incident rate — orders of magnitude below anything a single web endpoint worries about. The scaling questions that matter are downstream: queue worker concurrency, and whether a burst of failures (a regional outage triggering hundreds of simultaneous uptimeCheckFailed events) would stampede our alerting or ticketing system. Plan for burst fan-out and per-monitor alert throttling.

Failure modes

The two failure modes to fund explicitly are the silent ones: bad secret and unmapped event type. Everything else surfaces loudly.

Ramp-up

Genuinely low. A Laravel developer is productive in half a day from the README alone. The friction is documentation quality, not difficulty: the Usage section references (events) as a relative link in two places, which is broken prose rather than a working URL — so the event catalog must be sourced from Oh Dear's live docs, not from this repo. Budget an hour for someone to build the authoritative event-type list before any code is written; that artifact, not the package, is what future maintainers will actually lean on.