> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Okta Webhook Setup Guide

> Configure Okta to deliver events to StackOne.

## Prerequisites

The connector should already be set up, with a Connector Profile and a Linked Account. See [Getting Started](/connectors/okta#getting-started) on the Okta connector page.

<section data-guide-section data-guide-scopes="">
  <h2>Okta event hook setup</h2>

  <p>StackOne registers the Okta event hook, completes Okta's one-time endpoint verification, and deletes the hook when the account is disconnected. There is nothing to create in the Okta Admin Console. The items below are the Okta-side conditions that must hold for that to succeed.</p>

  <Steps>
    <Step title="Grant the connected admin permission to manage event hooks">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Event hooks are org-wide objects, and Okta restricts them to administrators. Make sure the identity you connect with holds the right role before linking the account.</p>

        <ul>
          <li><strong>Super Admin</strong> can create and manage event hooks by default.</li>
          <li>Alternatively, assign a custom admin role carrying the <strong>Manage event hooks</strong> permission (`okta.eventhooks.manage`). Custom permissions for hooks are a self-service Early Access feature, so an admin must enable it in <strong>Settings</strong> > <strong>Features</strong> first.</li>
          <li><strong>API Key:</strong> an Okta API token inherits the permissions of the admin who created it, so create the token while signed in as an account with one of the roles above.</li>
          <li><strong>OAuth 2.0:</strong> the `okta.eventHooks.manage` scope must be granted to the app and present in the <strong>Scopes</strong> field. A token refresh cannot add a scope, so after adding it you must re-link the account.</li>
        </ul>
      </div>
    </Step>

    <Step title="Check the org event hook limit">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Okta allows a maximum of 25 active and verified event hooks per org, and StackOne registers one hook per linked account. If the org is at the limit, hook creation fails.</p>

        <ul>
          <li>Review existing hooks in the Okta Admin Console under <strong>Workflow</strong> > <strong>Event Hooks</strong> and remove any that are no longer in use.</li>
        </ul>
      </div>
    </Step>

    <Step title="Allow Okta to reach the callback URL">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Immediately after creating the hook, Okta sends a single GET request carrying an `x-okta-verification-challenge` header, and StackOne echoes the value back to prove ownership of the endpoint. The hook only becomes ACTIVE once that exchange succeeds.</p>

        <ul>
          <li>Okta requires an HTTPS endpoint and will not accept an HTTP URL.</li>
          <li>If the hook remains UNVERIFIED in <strong>Workflow</strong> > <strong>Event Hooks</strong>, outbound traffic from Okta to the callback URL is being blocked — check any proxy or firewall rules, then disconnect and re-link the account to retry verification.</li>
        </ul>
      </div>
    </Step>

    <Step title="Leave the StackOne hook in place">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>The hook appears in the Okta Admin Console under <strong>Workflow</strong> > <strong>Event Hooks</strong>, named <strong>StackOne Event Hook</strong> unless you set a different value in the <strong>Event Hook Name</strong> field when connecting the account.</p>

        <ul>
          <li>Deactivating or deleting the hook in Okta stops delivery. StackOne does not recreate it automatically — disconnect and re-link the account to restore it.</li>
          <li>Do not add event hook filters to the StackOne hook, as filtered-out events are never delivered.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available webhook events</h2>

  <p>The following Okta event types can be enabled. StackOne subscribes the hook to exactly the events you select, and Okta does not deliver event types that are not subscribed. Only event types that Okta marks as event-hook eligible can be subscribed, which is why the list is narrower than the Okta System Log.</p>

  <Steps>
    <Step title="User events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events on Okta user accounts.</p>

        <ul>
          <li><strong>User Created</strong> (`user.lifecycle.create`) — Fired when a new user account is created</li>
          <li><strong>User Activated</strong> (`user.lifecycle.activate`) — Fired when a user becomes active and can sign in</li>
          <li><strong>User Deactivated</strong> (`user.lifecycle.deactivate`) — Fired when a user is deactivated and access is revoked</li>
          <li><strong>User Suspended</strong> (`user.lifecycle.suspend`) — Fired when a user is temporarily suspended</li>
          <li><strong>User Delete Initiated</strong> (`user.lifecycle.delete.initiated`) — Fired when a user deletion is requested</li>
          <li><strong>User Password Reset</strong> (`user.account.reset_password`) — Fired when a user's password is reset</li>
          <li><strong>User Profile Updated</strong> (`user.account.update_profile`) — Fired when user profile attributes change</li>
          <li><strong>User Universal Logout</strong> (`user.authentication.universal_logout`) — Fired when an admin or system account triggers Universal Logout against an app instance, revoking the user's sessions for that app</li>
        </ul>
      </div>
    </Step>

    <Step title="Group events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events on Okta groups and their membership.</p>

        <ul>
          <li><strong>Group Created</strong> (`group.lifecycle.create`) — Fired when a group is created</li>
          <li><strong>Group Deleted</strong> (`group.lifecycle.delete`) — Fired when a group is deleted</li>
          <li><strong>Group Member Added</strong> (`group.user_membership.add`) — Fired when a user is added to a group</li>
          <li><strong>Group Member Removed</strong> (`group.user_membership.remove`) — Fired when a user is removed from a group</li>
        </ul>
      </div>
    </Step>

    <Step title="Device events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events on devices registered in Okta. These three event types are only emitted by Okta Identity Engine orgs — a Classic Engine org never fires them, so subscribing to them there has no effect.</p>

        <ul>
          <li><strong>Device Activated</strong> (`device.lifecycle.activate`) — Fired when a device becomes active and trusted</li>
          <li><strong>Device Deactivated</strong> (`device.lifecycle.deactivate`) — Fired when a device loses its trusted status</li>
          <li><strong>Device Deleted</strong> (`device.lifecycle.delete`) — Fired when a device is removed from Okta</li>
        </ul>
      </div>
    </Step>

    <Step title="Application events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events on application assignments and sign-on policy decisions.</p>

        <ul>
          <li><strong>App User Assigned</strong> (`application.user_membership.add`) — Fired when a user is assigned to an application</li>
          <li><strong>App User Removed</strong> (`application.user_membership.remove`) — Fired when a user is removed from an application</li>
          <li><strong>App Sign-On Access Denied</strong> (`application.policy.sign_on.deny_access`) — Fired when an application sign-on policy denies a user access</li>
        </ul>
      </div>
    </Step>

    <Step title="System events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Security-critical events on Okta admin API tokens.</p>

        <ul>
          <li><strong>API Token Created</strong> (`system.api_token.create`) — Fired when an Okta admin API token is created</li>
          <li><strong>API Token Revoked</strong> (`system.api_token.revoke`) — Fired when an Okta admin API token is revoked</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.