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
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) feature. See Manage Early Access and Beta features 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
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) feature. See Manage Early Access and Beta features 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
{}