event_hooks

Creates, updates, deletes, gets or lists an event_hooks resource.

Overview

Name	event_hooks
Type	Resource
Id	okta.eventhooks.event_hooks

Fields

The following fields are returned by SELECT queries:

list_event_hooks

Name	Datatype	Description
id	string	Unique key for the event hook
name	string	Display name for the event hook
_links	object	Specifies link relations (see Web Linking) available using the JSON Hypertext Application Language specification. This object is used for dynamic discovery of related resources and lifecycle operations.
channel	object
created	string (date-time)	Timestamp of the event hook creation
createdBy	string	The ID of the user who created the event hook
description	string	Description of the event hook
events	object
lastUpdated	string (date-time)	Date of the last event hook update
status	string	Status of the event hook
verificationStatus	string	Verification status of the event hook. UNVERIFIED event hooks won't receive any events.

get_event_hook

Name	Datatype	Description
id	string	Unique key for the event hook
name	string	Display name for the event hook
_links	object	Specifies link relations (see Web Linking) available using the JSON Hypertext Application Language specification. This object is used for dynamic discovery of related resources and lifecycle operations.
channel	object
created	string (date-time)	Timestamp of the event hook creation
createdBy	string	The ID of the user who created the event hook
description	string	Description of the event hook
events	object
lastUpdated	string (date-time)	Date of the last event hook update
status	string	Status of the event hook
verificationStatus	string	Verification status of the event hook. UNVERIFIED event hooks won't receive any events.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list_event_hooks	select	subdomain		Lists all event hooks
get_event_hook	select	subdomain		Retrieves an event hook
create_event_hook	insert	subdomain, data__name, data__events, data__channel		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.
replace_event_hook	replace	subdomain, data__name, data__events, data__channel		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.
delete_event_hook	delete	subdomain		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.
activate_event_hook	exec	subdomain		Activates the event hook that matches the provided id
deactivate_event_hook	exec	subdomain		Deactivates the event hook that matches the provided id
verify_event_hook	exec	subdomain		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.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
subdomain	string	The domain of your organization. This can be a provided subdomain of an official okta domain (okta.com, oktapreview.com, etc) or one of your configured custom domains. (default: my-org)

SELECT examples

list_event_hooks

Lists all event hooks

SELECT
id,
name,
_links,
channel,
created,
createdBy,
description,
events,
lastUpdated,
status,
verificationStatus
FROM okta.eventhooks.event_hooks
WHERE subdomain = '{{ subdomain }}' -- required;

get_event_hook

Retrieves an event hook

SELECT
id,
name,
_links,
channel,
created,
createdBy,
description,
events,
lastUpdated,
status,
verificationStatus
FROM okta.eventhooks.event_hooks
WHERE subdomain = '{{ subdomain }}' -- required;

INSERT examples

create_event_hook

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.

INSERT INTO okta.eventhooks.event_hooks (
data__channel,
data__description,
data__events,
data__name,
subdomain
)
SELECT 
'{{ channel }}' --required,
'{{ description }}',
'{{ events }}' --required,
'{{ name }}' --required,
'{{ subdomain }}'
RETURNING
id,
name,
_links,
channel,
created,
createdBy,
description,
events,
lastUpdated,
status,
verificationStatus
;

Manifest

# Description fields are for documentation purposes
- name: event_hooks
  props:
    - name: subdomain
      value: string
      description: Required parameter for the event_hooks resource.
    - name: channel
      value: object
    - name: description
      value: string
      description: >
        Description of the event hook
        
    - name: events
      value: object
    - name: name
      value: string
      description: >
        Display name for the event hook
        

REPLACE examples

replace_event_hook

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.

REPLACE okta.eventhooks.event_hooks
SET 
data__channel = '{{ channel }}',
data__description = '{{ description }}',
data__events = '{{ events }}',
data__name = '{{ name }}'
WHERE 
subdomain = '{{ subdomain }}' --required
AND data__name = '{{ name }}' --required
AND data__events = '{{ events }}' --required
AND data__channel = '{{ channel }}' --required
RETURNING
id,
name,
_links,
channel,
created,
createdBy,
description,
events,
lastUpdated,
status,
verificationStatus;

DELETE examples

delete_event_hook

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.

DELETE FROM okta.eventhooks.event_hooks
WHERE subdomain = '{{ subdomain }}' --required;

Lifecycle Methods

activate_event_hook

Activates the event hook that matches the provided id

EXEC okta.eventhooks.event_hooks.activate_event_hook 
@subdomain='{{ subdomain }}' --required;

deactivate_event_hook

Deactivates the event hook that matches the provided id

EXEC okta.eventhooks.event_hooks.deactivate_event_hook 
@subdomain='{{ subdomain }}' --required;

verify_event_hook

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.

EXEC okta.eventhooks.event_hooks.verify_event_hook 
@subdomain='{{ subdomain }}' --required;