# Okta Webhooks

## When to Use This Skill

* Setting up Okta Event Hook handlers
* Implementing the one-time verification challenge (GET handshake)
* Authenticating Okta webhook requests with the `Authorization` header secret
* Understanding Okta event types and payloads
* Debugging why Okta event hook verification or delivery is failing

## How Okta Event Hooks Differ

Okta Event Hooks do not use an HMAC signature. Security relies on two things:

1. One-time verification handshake — When you register the hook, Okta sends a
  GET request with an `x-okta-verification-challenge` header. You must reply
  `200` with JSON `{"verification": "<challenge value>"}`.
2. Per-request authentication — You choose a secret string that Okta sends in
  the `Authorization` header on every event delivery (an HTTPS POST). Verify
  it with a timing-safe comparison. There is no body signature.

## Verification (core)

```javascript
const crypto = require('crypto');

// 1. One-time verification handshake (GET)
function handleChallenge(req, res) {
  const challenge = req.headers['x-okta-verification-challenge'];
  return res.status(200).json({ verification: challenge });
}

// 2. Per-request auth on every event POST — timing-safe compare of Authorization
function isAuthorized(authHeader, secret) {
  const a = Buffer.from(authHeader || '', 'utf8');
  const b = Buffer.from(secret || '', 'utf8');
  // Length check first: timingSafeEqual throws on unequal-length buffers
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

```

Python timing-safe compare: `hmac.compare_digest(auth_header, secret)`.

> For complete handlers with route wiring, event dispatch, and tests, see:
> 
> * [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/okta-webhooks/examples/express/)
> * [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/okta-webhooks/examples/nextjs/)
> * [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/okta-webhooks/examples/fastapi/)

## Common Event Types

Okta event hooks deliver [System Log](https://developer.okta.com/docs/reference/api/system-log/)
events. Each item in `data.events[]` has an `eventType` field:

| Event | Triggered When |
| --- | --- |
| `user.lifecycle.create` | A new user is created |
| `user.lifecycle.activate` | A user is activated |
| `user.session.start` | A user signs in to Okta |
| `user.account.lock` | A user account is locked |
| `user.account.unlock` | A user account is unlocked |
| `group.user_membership.add` | A user is added to a group |
| `group.user_membership.remove` | A user is removed from a group |

> For the full event catalog, see [Okta event types](https://developer.okta.com/docs/reference/api/event-types/?event-hook-eligible=true).

## Payload Structure

```json
{
  "eventType": "com.okta.event_hook",
  "eventTime": "2026-07-02T12:00:00.000Z",
  "eventId": "b5a4...",
  "data": {
    "events": [
      {
        "uuid": "d6f5...",
        "eventType": "user.session.start",
        "displayMessage": "User login to Okta",
        "published": "2026-07-02T12:00:00.000Z",
        "actor": { "id": "00u...", "type": "User", "alternateId": "jane@example.com" },
        "target": [ { "id": "00u...", "type": "User", "alternateId": "jane@example.com" } ]
      }
    ]
  }
}

```

The outer `eventType` is always `com.okta.event_hook`. The System Log event type
you dispatch on lives at `data.events[].eventType`.

## Environment Variables

```bash
OKTA_WEBHOOK_SECRET=your-shared-secret   # The Authorization header value you registered with Okta

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 okta --path /webhooks/okta

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/okta-webhooks/references/overview.md) - Okta Event Hook concepts and events
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/okta-webhooks/references/setup.md) - Register an event hook in the Okta Admin Console
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/okta-webhooks/references/verification.md) - Verification challenge + Authorization auth details