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:

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 (ACTIVE, INACTIVE)
verificationStatus	string	Verification status of the event hook. UNVERIFIED event hooks won't receive any events. (UNVERIFIED, VERIFIED)

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 (ACTIVE, INACTIVE)
verificationStatus	string	Verification status of the event hook. UNVERIFIED event hooks won't receive any events. (UNVERIFIED, VERIFIED)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_event_hook	select	eventHookId, subdomain		Retrieves an event hook
list_event_hooks	select	subdomain		Lists all event hooks
create_event_hook	insert	subdomain, name, events, 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	eventHookId, subdomain, name, events, 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	eventHookId, 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	eventHookId, subdomain		Activates the event hook that matches the provided id
deactivate_event_hook	exec	eventHookId, subdomain		Deactivates the event hook that matches the provided id
verify_event_hook	exec	eventHookId, 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
eventHookId	string	id of the Event Hook
subdomain	string	(default: my-org)

SELECT examples

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 eventHookId = '{{ eventHookId }}' -- required
AND subdomain = '{{ subdomain }}' -- required
;

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
;

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 (
channel,
description,
events,
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: "{{ subdomain }}"
    description: Required parameter for the event_hooks resource.
  - name: channel
    value:
      config:
        authScheme:
          key: "{{ key }}"
          type: "{{ type }}"
          value: "{{ value }}"
        headers:
          - key: "{{ key }}"
            value: "{{ value }}"
        method: "{{ method }}"
        uri: "{{ uri }}"
      type: "{{ type }}"
      version: "{{ version }}"
  - name: description
    value: "{{ description }}"
    description: |
      Description of the event hook
  - name: events
    value:
      filter:
        eventFilterMap:
          - condition:
              expression: "{{ expression }}"
              version: "{{ version }}"
            event: "{{ event }}"
        type: "{{ type }}"
      items:
        - "{{ items }}"
      type: "{{ type }}"
  - name: name
    value: "{{ name }}"
    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 
channel = '{{ channel }}',
description = '{{ description }}',
events = '{{ events }}',
name = '{{ name }}'
WHERE 
eventHookId = '{{ eventHookId }}' --required
AND subdomain = '{{ subdomain }}' --required
AND name = '{{ name }}' --required
AND events = '{{ events }}' --required
AND 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 eventHookId = '{{ eventHookId }}' --required
AND 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 
@eventHookId='{{ eventHookId }}' --required, 
@subdomain='{{ subdomain }}' --required
;

deactivate_event_hook

Deactivates the event hook that matches the provided id

EXEC okta.eventhooks.event_hooks.deactivate_event_hook 
@eventHookId='{{ eventHookId }}' --required, 
@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 
@eventHookId='{{ eventHookId }}' --required, 
@subdomain='{{ subdomain }}' --required
;