Test Okta event hooks locally

Start your appCopy Anchor Link

Okta does not sign event hook payloads. It sends a secret string of your choice in a header instead, and your service checks it. You pick the header name and the secret when you register the hook. This guide uses the header authorization.

Okta also makes a one-time GET request to verify that you own the endpoint. The request carries an x-okta-verification-challenge header. Return its value in a JSON object named verification. Every later event arrives as a POST with the events in a data.events array.

import { timingSafeEqual } from "node:crypto";

function hasValidSecret(request: Request) {
  const secret = process.env.OKTA_EVENT_HOOK_SECRET ?? "";
  const received = request.headers.get("authorization") ?? "";

  const receivedBuffer = Buffer.from(received);
  const secretBuffer = Buffer.from(secret);
  return (
    secret !== "" &&
    receivedBuffer.length === secretBuffer.length &&
    timingSafeEqual(receivedBuffer, secretBuffer)
  );
}

export async function GET(request: Request) {
  if (!hasValidSecret(request)) {
    return new Response("Unauthorized", { status: 401 });
  }

  const challenge = request.headers.get("x-okta-verification-challenge");
  return Response.json({ verification: challenge });
}

export async function POST(request: Request) {
  if (!hasValidSecret(request)) {
    return new Response("Unauthorized", { status: 401 });
  }

  const payload = await request.json();
  for (const event of payload.data.events) {
    console.log(`Received Okta event: ${event.eventType}`);
  }

  return new Response(null, { status: 204 });
}

Okta waits 3 seconds for an answer and retries at most once. It retries 5xx responses, not 4xx ones. Return 200 or 204 quickly.

Pick a secret and store it in an environment variable. Use a random, high-entropy string.

OKTA_EVENT_HOOK_SECRET=replace-with-a-long-random-string

Start the app on port 3000.

npm run dev

Start a tunnelCopy Anchor Link

Use -s with a subdomain you reserved. Without it, the subdomain is random and changes every run, so your Okta event hook would point at a dead URL after a restart. Reserved subdomains are a paid feature, see Pricing.

hrzn tunnel http://localhost:3000 -s my-app

HORIZON: Tunnel connected
  URL          https://my-app.hrzn.run (reserved)
  Forwarding   http://localhost:3000
  Request log  https://hrzn.run/dashboard/tunnels/my-app

Your public URL is https://my-app.hrzn.run. Keep this terminal open and keep the app running. Okta verifies the endpoint in the next step.

Add the event hook in OktaCopy Anchor Link

1. In the Admin Console, open Workflow, then Event Hooks.
2. Select Create Event Hook.
3. Enter a Name.
4. Enter https://my-app.hrzn.run/api/webhooks/okta as the URL.
5. Set the Authentication field to authorization.
6. Set the Authentication secret to the same value as OKTA_EVENT_HOOK_SECRET.
7. Subscribe to the events you want, for example User deactivated.
8. Select Save & Continue.
9. Select Verify.

Okta sends the verification GET now. When it succeeds, the hook's status shows VERIFIED.

Preview an eventCopy Anchor Link

Okta lets you test a verified hook with sample or historical event data. Open the hook's Actions menu and select Preview.