Register the event hook in the Okta Admin Console or via the Event Hooks API (POST /api/v1/eventHooks) with the hookUrl, the event types to subscribe to (e.g. user.session.start, user.authentication.auth_via_mfa), and an authorization header secret
Implement the challenge verification step: when Okta first activates the hook, it sends a GET request to your hookUrl with an X-Okta-Verification-Challenge header; respond with {verification: <value-from-header>} and HTTP 200
Handle incoming event payloads: each POST contains an events array; each event object has eventType, target[], actor, client, and an outcome field indicating success or failure
Respond within Okta's timeout (currently 3 seconds); return HTTP 200 promptly and process the event asynchronously in a background queue — synchronous heavy processing will cause timeout failures and retries
Verify the request came from Okta: check the Authorization header value against your configured secret before processing the event
Use the event hook to trigger downstream actions: update a SIEM, enforce geo-block policies, trigger re-authentication prompts, or feed a risk engine — but do not use the event hook for inline authentication decisions (use inline hooks for that)
Known gotchas
Event hooks deliver events asynchronously and at-least-once; your handler must be idempotent — use the event's uuid field to deduplicate redeliveries
Okta retries failed deliveries with exponential backoff; if your endpoint is consistently slow or returning errors, the hook will be automatically deactivated after repeated failures — monitor hook delivery health in the Okta System Log
Event hooks fire after the event has occurred — they cannot block or modify the authentication flow; use Okta Inline Hooks for synchronous policy enforcement during login
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp