Event Hooks

The Event Hooks API provides operations to manage event hooks for your organization.

For general information on event hooks and how to create and use them, see Event hooks. The following documentation is only for the management API, which provides a CRUD interface for registering event hooks.

For a step-by-step guide on implementing an example event hook, see the Event hook guide.

When you create an event hook, you need to specify which events you want to subscribe to. To see the list of event types currently eligible for use in event hooks, use the Event Types catalog and search with the parameter event-hook-eligible.

List all Event Hooks
OAuth 2.0: okta.eventHooks.read

Lists all event hooks

Responses
200

Success

403

Forbidden

429

Too Many Requests

get/api/v1/eventHooks
Request samples
Response samples
application/json
[]

Create an Event Hook
OAuth 2.0: okta.eventHooks.manage

Creates a new event hook for your organization in ACTIVE status. You pass an event hook object in the JSON payload of your request. That object represents the set of required information about the event hook you're registering, including:

  • The URI of your external service

  • The events in Okta you want to subscribe to

  • An optional event hook filter that can reduce the number of event hook calls. This is a self-service Early Access (EA) feature. See Create an event hook filter.

    Additionally, you can specify a secret API key for Okta to pass to your external service endpoint for security verification. Note that the API key you set here is unrelated to the Okta API token

you must supply when making calls to Okta APIs. Optionally, you can specify extra headers that Okta passes to your external service with each call. Your external service must use a valid HTTPS endpoint.

Request
Request Body schema: application/json
required
required
object (EventHookChannel)
required
object (EventHookChannelConfig)
object (EventHookChannelConfigAuthScheme)

The authentication scheme used for this request.

To use Basic Auth for authentication, set type to HEADER, key to Authorization, and value to the Base64-encoded string of "username:password". Ensure that you include the scheme (including space) as part of the value parameter. For example, Basic YWRtaW46c3VwZXJzZWNyZXQ=. See HTTP Basic Authentication.

Array of objects or null (EventHookChannelConfigHeader)

Optional list of key/value pairs for headers that can be sent with the request to the external service. For example, X-Other-Header is an example of an optional header, with a value of my-header-value, that you want Okta to pass to your external service.

uri
required
string

The external service endpoint called to execute the event hook handler

type
required
string (EventHookChannelType)

The channel type. Currently supports HTTP.

Value: "HTTP"
version
required
string

Version of the channel. Currently the only supported version is `1.0.0``.

description
string or null

Description of the event hook

required
object (EventSubscriptions)
object or null (EventHookFilters)

The optional filter defined on a specific event type

Note: Event hook filters is a self-service Early Access (EA) to enable. If you want to disable this feature, it's recommended to first remove all event filters.

Array of objects (EventHookFilterMap)

The object that maps the filter to the event type

items
required
Array of strings (EventHookSubscribedEventTypes)

The subscribed event types that trigger the event hook. When you register an event hook you need to specify which events you want to subscribe to. To see the list of event types currently eligible for use in event hooks, use the Event Types catalog and search with the parameter event-hook-eligible.

type
required
string (EventSubscriptionType)

The events object type. Currently supports EVENT_TYPE.

Value: "EVENT_TYPE"
name
required
string

Display name for the event hook

Responses
200

Success

400

Bad Request

403

Forbidden

429

Too Many Requests

post/api/v1/eventHooks
Request samples
application/json
{
  • "name": "Event Hook Test",
  • "events": {
    • "type": "EVENT_TYPE",
    • "items": [
      ]
    },
  • "channel": {
    • "type": "HTTP",
    • "version": "1.0.0",
    • "config": {}
    }
}
Response samples
application/json
{}

Retrieve an Event Hook
OAuth 2.0: okta.eventHooks.read

Retrieves an event hook

Request
path Parameters
eventHookId
required
string

id of the Event Hook

Example: who8vt36qfNpCGz9H1e6
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/eventHooks/{eventHookId}
Request samples
Response samples
application/json
{}

Replace an Event Hook
OAuth 2.0: okta.eventHooks.manage

Replaces an event hook. Okta validates the new properties before replacing the existing values. Some event hook properties are immutable and can't be updated. Refer to the parameter description in the request body schema.

Note: Updating the channel property requires you to verify the hook again.

Request
path Parameters
eventHookId
required
string

id of the Event Hook

Example: who8vt36qfNpCGz9H1e6
Request Body schema: application/json
required
required
object (EventHookChannel)
required
object (EventHookChannelConfig)
object (EventHookChannelConfigAuthScheme)

The authentication scheme used for this request.

To use Basic Auth for authentication, set type to HEADER, key to Authorization, and value to the Base64-encoded string of "username:password". Ensure that you include the scheme (including space) as part of the value parameter. For example, Basic YWRtaW46c3VwZXJzZWNyZXQ=. See HTTP Basic Authentication.

Array of objects or null (EventHookChannelConfigHeader)

Optional list of key/value pairs for headers that can be sent with the request to the external service. For example, X-Other-Header is an example of an optional header, with a value of my-header-value, that you want Okta to pass to your external service.

uri
required
string

The external service endpoint called to execute the event hook handler

type
required
string (EventHookChannelType)

The channel type. Currently supports HTTP.

Value: "HTTP"
version
required
string

Version of the channel. Currently the only supported version is `1.0.0``.

description
string or null

Description of the event hook

required
object (EventSubscriptions)
object or null (EventHookFilters)

The optional filter defined on a specific event type

Note: Event hook filters is a self-service Early Access (EA) to enable. If you want to disable this feature, it's recommended to first remove all event filters.

Array of objects (EventHookFilterMap)

The object that maps the filter to the event type

items
required
Array of strings (EventHookSubscribedEventTypes)

The subscribed event types that trigger the event hook. When you register an event hook you need to specify which events you want to subscribe to. To see the list of event types currently eligible for use in event hooks, use the Event Types catalog and search with the parameter event-hook-eligible.

type
required
string (EventSubscriptionType)

The events object type. Currently supports EVENT_TYPE.

Value: "EVENT_TYPE"
name
required
string

Display name for the event hook

Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

put/api/v1/eventHooks/{eventHookId}
Request samples
application/json
{
  • "name": "Event Hook with Filter",
  • "description": "An event hook using an Okta Expression Language filter",
  • "events": {
    • "type": "EVENT_TYPE",
    • "items": [
      ],
    • "filter": {
      }
    },
  • "channel": {}
}
Response samples
application/json
{}

Delete an Event Hook
OAuth 2.0: okta.eventHooks.manage

Deletes the event hook that matches the provided id. After deletion, the event hook is unrecoverable. As a safety precaution, you can only delete event hooks with a status of INACTIVE.

Request
path Parameters
eventHookId
required
string

id of the Event Hook

Example: who8vt36qfNpCGz9H1e6
Responses
204

No Content

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/eventHooks/{eventHookId}
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

Activate an Event Hook
OAuth 2.0: okta.eventHooks.manage

Activates the event hook that matches the provided id

Request
path Parameters
eventHookId
required
string

id of the Event Hook

Example: who8vt36qfNpCGz9H1e6
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/eventHooks/{eventHookId}/lifecycle/activate
Request samples
Response samples
application/json
{}

Deactivate an Event Hook
OAuth 2.0: okta.eventHooks.manage

Deactivates the event hook that matches the provided id

Request
path Parameters
eventHookId
required
string

id of the Event Hook

Example: who8vt36qfNpCGz9H1e6
Responses
200

Success

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/eventHooks/{eventHookId}/lifecycle/deactivate
Request samples
Response samples
application/json
{}

Verify an Event Hook
OAuth 2.0: okta.eventHooks.manage

Verifies that the event hook matches the provided eventHookId. To verify ownership, your endpoint must send information back to Okta in JSON format. See Event hooks.

Only ACTIVE and VERIFIED event hooks can receive events from Okta.

If a response is not received within 3 seconds, the outbound request times out. One retry is attempted after a timeout or error response. If a successful response still isn't received, this operation returns a 400 error with more information about the failure.

Request
path Parameters
eventHookId
required
string

id of the Event Hook

Example: who8vt36qfNpCGz9H1e6
Responses
200

Success

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/eventHooks/{eventHookId}/lifecycle/verify
Request samples
Response samples
application/json
{}