In the Okta Admin Console, navigate to Workflow > Event Hooks and click Create Event Hook, supplying your endpoint URL and the events to subscribe to.
Save the hook; Okta immediately sends a one-time GET request to your endpoint containing the verification value in the request header named x-okta-verification-challenge.
Your endpoint must read that header value and return it in a JSON response body: {"verification": "<value-from-header>"}.
Click Verify in the console (or call the verify API) after your endpoint is deployed and responding correctly.
Test delivery by triggering a subscribed event and inspecting the POST payload your endpoint receives; each delivery is a signed JSON object with an events array.
Implement HMAC-SHA256 signature verification using the secret set on the hook to authenticate every subsequent POST from Okta.
Known gotchas
The verification value is in the x-okta-verification-challenge REQUEST HEADER on the GET, not the request body; reading the wrong location will fail verification silently.
Subsequent event deliveries are POST requests, not GET; your route handler must handle both methods or use separate routes.
If your endpoint returns a non-2xx status during verification, Okta marks the hook as unverified and stops delivery until you re-verify.
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