Is it easy or difficult to use our developer documentation? Let us know in this short survey ↗

On this page

Event Hooks Management API

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.

Get started

Explore the event hooks API: Run in Postman (opens new window)

Event hook operations

Create event hook

POST /api/v1/eventHooks

Registers a new event hook to your organization in ACTIVE status. You need to 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 are registering, including:

  • The URI of your external service endpoint.
  • The events in Okta you want to subscribe to.

Additionally, the object lets you specify a secret API key that you want Okta to pass to your external service endpoint (so that your external service can check for its presence as a security measure).

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 you wish Okta to pass to your external service with each call.

Your external service's endpoint needs to be a valid HTTPS endpoint, where the URI you specify should always begin with https://.

Request parameters
Parameter Description Param Type DataType Required
Event Hook A valid Event Hook object that specifies the details of the event hook that you are registering Body Event Hook object TRUE
Response parameters

The response is an Event Hook object that represents the event hook that was registered. The id property returned in the response serves as the unique ID for the registered event hook, which you can specify when invoking other CRUD operations.

Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
    "name" : "My Test Event Hook",
    "events" : {
        "type" : "EVENT_TYPE",
        "items" : [
            "user.lifecycle.create",
            "user.lifecycle.activate"
        ],
        "filter" : null
    },
    "channel" : {
        "type" : "HTTP",
        "version" : "1.0.0",
        "config" : {
            "uri" : "https://www.example.com/eventHooks",
            "headers" : [
                {
                    "key" : "X-Other-Header",
                    "value" : "some-other-value"
                }
            ],
            "authScheme" : {
                "type" : "HEADER",
                "key" : "Authorization",
                "value" : "${api-key}"
            }
        }
    }
}' "https://${yourOktaDomain}/api/v1/eventHooks"

Note: X-Other-Header is an example of an additional optional header, with its value specified as some-other-value. For each optional header, you choose the name and value you wish Okta to pass to your external service.

Response example
{
    "id": "whor0dvWvbMQJHZCM0g3",
    "name" : "My Test Event Hook",
    "status": "ACTIVE",
    "verificationStatus": "UNVERIFIED",
    "events" : {
        "type" : "EVENT_TYPE",
        "items" : [
            "user.lifecycle.create",
            "user.lifecycle.activate"
        ],
        "filter": null
    },
    "channel" : {
        "type" : "HTTP",
        "version" : "1.0.0",
        "config" : {
            "uri" : "https://www.example.com/eventHooks",
            "method" : "POST",
            "headers" : [
                {
                    "key" : "X-Other-Header",
                    "value" : "some-other-value"
                }
            ],
            "authScheme" : {
                "type" : "HEADER",
                "key" : "Authorization"
            }
        }
    },
    "created": "2018-05-15T01:23:08.000Z",
    "lastUpdated": "2018-05-15T01:23:08.000Z"
}

Note: The channel.authScheme.value property is not returned in the response. You set it in your request, but it is not exposed in any responses.

Get event hook

GET /api/v1/eventHooks/${id}

Request parameters
Parameter Description Param Type DataType Required
id A valid event hook ID Path String TRUE
Response parameters

The response is an Event Hook object that represents the registered event hook that matches the id you specified.

Request example
curl -v -X GET \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/eventHooks/${id}"
Response example
{
    "id": "whor0dvWvbMQJHZCM0g3",
    "name" : "My Test Event Hook",
    "status": "ACTIVE",
    "verificationStatus": "UNVERIFIED",
    "events" : {
        "type" : "EVENT_TYPE",
        "items" : [
            "user.lifecycle.create",
            "user.lifecycle.activate"
        ],
        "filter" : null
    },
    "channel" : {
        "type" : "HTTP",
        "version" : "1.0.0",
        "config" : {
            "uri" : "https://www.example.com/eventHooks",
            "method" : "POST",
            "headers" : [
                {
                    "key" : "X-Other-Header",
                    "value" : "some-other-value"
                }
            ],
            "authScheme" : {
                "type" : "HEADER",
                "key" : "Authorization"
            }
        }
    },
    "created": "2018-05-15T01:23:08.000Z",
    "lastUpdated": "2018-05-15T01:23:08.000Z"
}

List event hooks

GET /api/v1/eventHooks

Returns a list of registered event hooks

Request example
curl -v -X GET \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/eventHooks"
Response example
[
  {
    "id": "whor0dvWvbMQJHZCM0g3",
    "name" : "My Test Event Hook",
    "status": "ACTIVE",
    "verificationStatus": "UNVERIFIED",
    "events" : {
        "type" : "EVENT_TYPE",
        "items" : [
            "user.lifecycle.create",
            "user.lifecycle.activate"
        ],
        "filter" : null
    },
    "channel" : {
        "type" : "HTTP",
        "version" : "1.0.0",
        "config" : {
            "uri" : "https://www.example.com/eventHooks",
            "method" : "POST",
            "headers" : [
                {
                    "key" : "X-Other-Header",
                    "value" : "some-other-value"
                }
            ],
            "authScheme" : {
                "type" : "HEADER",
                "key" : "Authorization"
            }
        }
    },
    "created": "2018-05-15T01:23:08.000Z",
    "lastUpdated": "2018-05-15T01:23:08.000Z"
  }
]

Update event hook

PUT /api/v1/eventHooks/${id}

Request parameters
Parameter Description Param Type DataType Required
eventHook An eventHook object that represents the updated properties that you want to apply Body Event Hook Object TRUE
id The ID of the event hook that you want to update Path String TRUE

The submitted event hook properties replace the existing properties after passing validation. Note that some properties are immutable and cannot be updated. Refer to the description of each property in the Event Hook object table for information.

Response parameters

The response is an Event Hook object that represents the updated event hook.

Request example
curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
    "name" : "My Test Event Hook Updated",
    "events" : {
        "type" : "EVENT_TYPE",
        "items" : [
            "user.lifecycle.create",
            "user.lifecycle.activate",
            "user.lifecycle.deactivate"
        ],
        "filter" : null
    },
    "channel" : {
        "type" : "HTTP",
        "version" : "1.0.0",
        "config" : {
            "uri" : "https://www.example.com/eventHooks",
            "headers" : [
                {
                    "key" : "X-Other-Header",
                    "value" : "some-other-value-updated"
                }
            ],
            "authScheme" : {
                "type" : "HEADER",
                "key" : "Authorization",
                "value" : "${api-key-updated}"
            }
        }
    }
}' "https://${yourOktaDomain}/api/v1/eventHooks/${id}"
Response example
{
    "id": "whor0dvWvbMQJHZCM0g3",
    "name" : "My Test Event Hook Updated",
    "status": "ACTIVE",
    "verificationStatus": "UNVERIFIED",
    "events" : {
        "type" : "EVENT_TYPE",
        "items" : [
            "user.lifecycle.create",
            "user.lifecycle.activate",
            "user.lifecycle.deactivate"
        ],
        "filter" : null
    },
    "channel" : {
        "type" : "HTTP",
        "version" : "1.0.0",
        "config" : {
            "uri" : "https://www.example.com/eventHooks",
            "method" : "POST",
            "headers" : [
                {
                    "key" : "X-Other-Header",
                    "value" : "some-other-value-updated"
                }
            ],
            "authScheme" : {
                "type" : "HEADER",
                "key" : "Authorization"
            }
        }
    },
    "created": "2018-05-15T01:23:08.000Z",
    "lastUpdated": "2018-05-15T01:23:08.000Z"
}

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

Verify event hook

POST /api/v1/eventHooks/${id}/lifecycle/verify

Parameter Description Param Type DataType Required
id ID of the event hook to verify Path String TRUE

Verifies that the event hook matches the provided eventHookId. Your endpoint needs to be able to correctly send back information to Okta in JSON format, so that endpoint ownership can be verified. See Event hooks.

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

A timeout of three seconds is enforced on all outbound requests, with one retry in the event of a timeout or an error response from the remote system. If a successful response has not been received after that, a 400 error is returned with more information about what failed.

Request example
curl -v -X POST \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/eventHooks/${id}/lifecycle/verify"
Response example
{
    "id": "whor0dvWvbMQJHZCM0g3",
    "name" : "My Test Event Hook",
    "status": "ACTIVE",
    "verificationStatus": "VERIFIED",
    "events" : {
        "type" : "EVENT_TYPE",
        "items" : [
            "user.lifecycle.create",
            "user.lifecycle.activate"
        ],
        "filter" : null
    },
    "channel" : {
        "type" : "HTTP",
        "version" : "1.0.0",
        "config" : {
            "uri" : "https://www.example.com/eventHooks",
            "method" : "POST",
            "headers" : [
                {
                    "key" : "X-Other-Header",
                    "value" : "some-other-value"
                }
            ],
            "authScheme" : {
                "type" : "HEADER",
                "key" : "Authorization"
            }
        }
    },
    "created": "2018-05-15T01:23:08.000Z",
    "lastUpdated": "2018-05-15T01:23:08.000Z"
}

Activate event hook

POST /api/v1/eventHooks/${id}/lifecycle/activate

Request parameters
Parameter Description Param Type DataType Required
id The ID of the event hook to activate Path String TRUE

Activates the event hook that matches the provided id

Response parameters

The response is an Event Hook object that represents the activated event hook.

Request example
curl -v -X POST \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/eventHooks/${id}/lifecycle/activate"
Response example
{
    "id": "whor0dvWvbMQJHZCM0g3",
    "name" : "My Test Event Hook",
    "status": "ACTIVE",
    "verificationStatus": "VERIFIED",
    "events" : {
        "type" : "EVENT_TYPE",
        "items" : [
            "user.lifecycle.create",
            "user.lifecycle.activate"
        ],
        "filter" : null
    },
    "channel" : {
        "type" : "HTTP",
        "version" : "1.0.0",
        "config" : {
            "uri" : "https://www.example.com/eventHooks",
            "method" : "POST",
            "headers" : [
                {
                    "key" : "X-Other-Header",
                    "value" : "some-other-value"
                }
            ],
            "authScheme" : {
                "type" : "HEADER",
                "key" : "Authorization"
            }
        }
    },
    "created": "2018-05-15T01:23:08.000Z",
    "lastUpdated": "2018-05-15T01:23:08.000Z"
}

Deactivate event hook

POST /api/v1/eventHooks/${id}/lifecycle/deactivate

Request parameters
Parameter Description Param Type DataType Required
id The ID of the event hook to deactivate Path String TRUE

Deactivates the event hook that matches the provided id

Response parameters

The response is an Event Hook object that represents the deactivated event hook.

Request example
curl -v -X POST \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/eventHooks/${id}/lifecycle/deactivate"
Response example
{
    "id": "whor0dvWvbMQJHZCM0g3",
    "name" : "My Test Event Hook",
    "status": "INACTIVE",
    "verificationStatus": "VERIFIED",
    "events" : {
        "type" : "EVENT_TYPE",
        "items" : [
            "user.lifecycle.create",
            "user.lifecycle.activate"
        ],
        "filter" : null
    },
    "channel" : {
        "type" : "HTTP",
        "version" : "1.0.0",
        "config" : {
            "uri" : "https://www.example.com/eventHooks",
            "method" : "POST",
            "headers" : [
                {
                    "key" : "X-Other-Header",
                    "value" : "some-other-value"
                }
            ],
            "authScheme" : {
                "type" : "HEADER",
                "key" : "Authorization"
            }
        }
    },
    "created": "2018-05-15T01:23:08.000Z",
    "lastUpdated": "2018-05-15T01:23:08.000Z"
}

Delete event hook

DELETE /api/v1/eventHooks/${id}

Request parameters
Parameter Description Param Type DataType Required
id The ID of the event hook to delete Path String TRUE

Deletes the event hook that matches the provided id. Once deleted, the event hook is unrecoverable. As a safety precaution, only event hooks with a status of INACTIVE are eligible for deletion.

Response parameters

All responses return a 204 status with no content.

Request example
curl -v -X DELETE \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/eventHooks/${id}"
Response example

204 with no content

Event Hook object

Property Description DataType Nullable Unique ReadOnly Validation
channel object Properties of the communications channel used to contact your external service Channel object FALSE FALSE FALSE Validation is determined by the specific channel.
created Date of event hook creation String (Date) TRUE FALSE TRUE System assigned
events Events subscribed by this hook Events object FALSE TRUE FALSE Validation is determined by the specific event object type.
id Unique key for the event hook String FALSE TRUE TRUE System assigned
lastUpdated Date of event hook update String (Date) TRUE FALSE TRUE System assigned
name Display name for the event hook String FALSE TRUE FALSE Must be between one and 255 characters in length
status Status of the event hook. INACTIVE doesn't receive any events. String FALSE FALSE FALSE System assigned. Will be either ACTIVE or INACTIVE.
verificationStatus Verification status of the event hook. UNVERIFIED will not receive any events. String FALSE FALSE FALSE System assigned. Will be either VERIFIED or UNVERIFIED.
{
    "name" : "My Test Event Hook",
    "status" : "ACTIVE",
    "verificationStatus" : "VERIFIED",
    "events" : {
        "type" : "EVENT_TYPE",
        "items" : [
            "user.lifecycle.create",
            "user.lifecycle.activate"
        ],
        "filter" : null
    },
    "channel" : {
        "type" : "HTTP",
        "version" : "1.0.0",
        "config" : {
            "uri" : "https://www.example.com/eventHooks",
            "headers" : [
                {
                    "key" : "X-Other-Header",
                    "value" : "some-other-value"
                }
            ],
            "authScheme" : {
                "type" : "HEADER",
                "key" : "Authorization",
                "value" : "${api-key}"
            }
        }
    },
    "created": "2018-05-15T01:23:08.000Z",
    "lastUpdated": "2018-05-15T01:23:08.000Z"
}

Channel object

Property Description DataType Nullable Unique ReadOnly Validation
config Properties of the communications channel used to contact your external service Channel Config object FALSE FALSE FALSE Validation is determined by the specific channel.
type The channel type. Currently the only supported type is HTTP. string FALSE FALSE TRUE Must match a valid channel type
version Version of the channel. The currently-supported version is "1.0.0". String FALSE FALSE TRUE Must match a valid version number

Config object

Property Description DataType Required Unique ReadOnly Validation
authScheme The authentication scheme to use for this request AuthScheme object FALSE FALSE FALSE Valid authscheme object
headers Optional list of key/value pairs for headers that should be sent with the request to the external service JSON Object FALSE FALSE FALSE Some reserved headers, such as Accept, are disallowed.
uri External service endpoint to call to execute the event hook handler String TRUE FALSE TRUE Must begin with https://. Maximum length 1024 characters. No white space allowed. The URI must be reachable by Okta.

AuthScheme object

Property Description DataType Required ReadOnly
key The header name for the authorization header String TRUE FALSE
type The authentication scheme type. Currently the only supported type is HEADER. String TRUE FALSE
value The header value. This secret value is passed to your external service endpoint. Your external service can check for it as a security measure. String TRUE TRUE

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

Events object

Property Description DataType Required ReadOnly
type The events object type. Currently the only supported type is EVENT_TYPE. String TRUE FALSE
items The event types to subscribe to Array of String TRUE FALSE
filter The filter defined on a specific event type filter object FALSE FALSE
Example of events object

"events": {
            "type": "EVENT_TYPE",
            "items": [
                "user.session.end",
                "user.session.start"
            ],
            "filter": {
                "type": "EXPRESSION_LANGUAGE",
                "eventFilterMap": [
                    {
                        "event": "user.session.end",
                        "condition": {
                            "version": null,
                            "expression": "event.eventType eq 'Admin' && event.eventType ne 'Bob'"
                        }
                    }
                ]
            }
        }

Filter object

Property Description DataType Required ReadOnly
type The type of filter. Okta only supports EXPRESSION_LANGUAGE String TRUE TRUE
eventFilterMap The object that maps the filter to the event type Array of eventFilterMap objects FALSE FALSE

Event filter map object

Early Access

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.

Explore the event hooks API with filters: Run in Postman (opens new window)

Property Description DataType Required ReadOnly
event The filtered event type String TRUE FALSE
condition The object that defines the filter condition object TRUE FALSE

Condition object

Property Description DataType Required ReadOnly
version Internal field String TRUE TRUE
expression The Okta Expression language statement that filters the event type String TRUE FALSE

Supported events for subscription

When you register an event hook, you need to specify what 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.