POST /api/v1/eventHooks

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.

Servers

https://{yourOktaDomain}

Request headers

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"

Request body fields

Name	Type	Required	Description
`id`	String	No	Unique key for the event hook
`channel`	Object	Yes
`channel.config`	Object	Yes
`channel.config.uri`	String	Yes	The external service endpoint called to execute the event hook handler
`channel.config.authScheme`	Object	No	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=`.
`channel.config.authScheme.key`	String	No	The name for the authorization header
`channel.config.authScheme.type`	String	No	The authentication scheme type. Currently only supports `HEADER`. Possible values: `"HEADER"`
`channel.config.authScheme.value`	String	No	The header value. This secret key is passed to your external service endpoint for security verification. This property is not returned in the response.
`channel.config.method`	String	No	The method of the Okta event hook request
`channel.config.headers[]`	Array	No	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.
`channel.config.headers[].key`	String	No	The optional field or header name
`channel.config.headers[].value`	String	No	The value for the key
`channel.version`	String	Yes	Version of the channel. Currently the only supported version is `1.0.0``.
`channel.type`	String	Yes	The channel type. Currently supports `HTTP`. Possible values: `"HTTP"`
`created`	String	No	Timestamp of the event hook creation
`name`	String	Yes	Display name for the event hook
`description`	String	No	Description of the event hook
`events`	Object	Yes
`events.filter`	Object	No	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.
`events.filter.type`	String	No	The type of filter. Currently only supports `EXPRESSION_LANGUAGE`
`events.filter.eventFilterMap[]`	Array	No	The object that maps the filter to the event type
`events.filter.eventFilterMap[].condition`	Object	No
`events.filter.eventFilterMap[].condition.expression`	String	No	The Okta Expression language statement that filters the event type
`events.filter.eventFilterMap[].condition.version`	String	No	Internal field
`events.filter.eventFilterMap[].event`	String	No	The filtered event type
`events.items[]`	Array	Yes	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`.
`events.type`	String	Yes	The events object type. Currently supports `EVENT_TYPE`. Possible values: `"EVENT_TYPE"`
`status`	String	No	Status of the event hook Possible values: `"ACTIVE"` `"INACTIVE"`
`verificationStatus`	String	No	Verification status of the event hook. `UNVERIFIED` event hooks won't receive any events. Possible values: `"VERIFIED"` `"UNVERIFIED"`
`createdBy`	String	No	The ID of the user who created the event hook
`lastUpdated`	String	No	Date of the last event hook update

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.