Okta Event Laravel Package

Getting Started

Install the package and publish its config:

composer require ilbee/okta-event:^1.0.1
php artisan vendor:publish --tag=okta-event-config

Set the shared secret Okta will send on every request (the X-Auth-Token header as of v1.0.1) in .env, then php artisan config:cache. The config file is the first place to look — it defines the auth token, the route/URI the webhook is exposed on, any IP or payload-size limits, and the mapping between Okta event types and the Laravel events/jobs the package fires.

First use case: register the webhook in Okta (Security → Event Hooks → Add), pointing at your package route and supplying the same token in the hook's authentication header. Okta immediately issues a verification GET; the package echoes the X-Okta-Verification-Challenge back as JSON, which flips the hook to "Verified". Only then will Okta start POSTing events. Locally, expose php artisan serve through a tunnel (ngrok/Expose) so Okta can reach it, or fake the two calls by hand:

curl -i https://your-tunnel.test/okta/events \
  -H "X-Auth-Token: $OKTA_EVENT_TOKEN" \
  -H "X-Okta-Verification-Challenge: abc123"

curl -i -X POST https://your-tunnel.test/okta/events \
  -H "X-Auth-Token: $OKTA_EVENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d @tests/fixtures/okta-user-login.json

Implementation Patterns

Verify in Okta, then subscribe in code. The natural workflow is: configure the hook in Okta, let verification succeed, then start listening. Attach listeners to the package's dispatched events (or, if the package exposes a single OktaEventReceived event, branch on $event->type) and keep listeners thin — push real work onto queued jobs so the endpoint returns 200 fast enough to stay inside Okta's timeout.

Treat the endpoint as a transport, not a controller. Don't add business logic to the route. The package's job is auth, content-type gating, payload-size rejection and deserialization; yours is idempotent processing. Store the Okta event uuid/id (or a hash of it) and short-circuit duplicates, because Okta retries failed deliveries and can redeliver on its own schedule.

Testing pattern. Use postJson() in feature tests so Content-Type: application/json is set for you, and always include the auth header:

$this->withHeaders(['X-Auth-Token' => config('okta-event.token')])
     ->postJson('/okta/events', $payload)
     ->assertOk();

Keep a small fixture directory of real Okta payloads per event type (user.lifecycle.activate, group.user_membership.add, etc.) and drive listeners from those — it doubles as documentation of which event types you actually rely on.

Integration tips. Keep the webhook route out of the web middleware group (no CSRF, no session) — check the package's route registration if you're mounting it under a custom prefix or behind auth middleware. When you need per-event fan-out, prefer a single listener that switches on event type and dispatches typed jobs, so the Okta payload shape is normalised in one place. If you run multiple environments against one Okta org, create a separate hook per environment so tokens and URLs stay isolated.

Gotchas and Tips

v1.0.1 tightened the front door — expect 415s and 401s after upgrading. The three changes are all pre-deserialization rejections:

• The verification GET now requires X-Auth-Token. If your Okta hook was configured without an authentication header (some setups only set it on the event POST), re-verification will fail with 401 and Okta will show the hook as unverified. Update the hook config before rolling out.
• Requests missing or with a non-application/json Content-Type now return 415 instead of being parsed anyway. Hand-rolled curl calls, Postman collections and older internal fakes will start failing; postJson() in tests is unaffected.
• Content-Length is pre-checked to reject oversized payloads early. Watch for proxies or load balancers that strip Content-Length or forward chunked transfer encoding — those requests have no length header and can be rejected before your code sees them. If you see intermittent rejections only in staging/production, compare the headers arriving at PHP-FPM, not at the client.

Okta hides these failures. A 401/415 shows up in Okta as a delivery failure with retries, not as an obvious error in your app logs — the request may never reach your listener. Add logging at the HTTP layer (or enable the package's debug logging if it has a config flag) when first wiring an environment up.

Rotating the token means two changes. Update .env, run php artisan config:cache, and update the header value in the Okta hook. Config caching is the classic forgotten step: the old token keeps validating until the cache is rebuilt, which masks the rotation and then breaks loudly later.

Don't rely on Content-Length for your own limits. The package rejects early, but PHP's post_max_size / upload_max_filesize still apply and can hand you an empty $_POST/body with no error. If you expect large batches, size the PHP limits above your configured package limit.

Extension points worth knowing. The event-type → Laravel event mapping and the route registration are the two seams most teams need to touch: remap or add event types in config rather than editing vendor code, and override the route (prefix, domain, middleware) in config if the default URI collides with an existing endpoint. If you need custom rejection semantics (e.g. return 400 instead of 415 for a noisy internal client), that belongs in a small middleware ahead of the package route, not a fork.

Pin the patch. Because v1.0.1 changes request-acceptance behaviour without changing the public API, pin ^1.0.1 in composer.json and re-run your webhook integration tests on upgrade — a passing unit suite won't catch a header your HTTP client stopped sending.