Instructions for

Event hook implementation

This guide provides a working example of an Okta event hook. It uses the website Glitch.com (opens new window) to act as an external service and receive and respond to Okta event hook calls.

Learning outcomes

Understand the Okta event hook calls and responses.
Implement a working example of an Okta event hook with a Glitch.com project, which acts as an external service.
Preview and test an Okta event hook.

What you need

Okta Developer Edition organization (opens new window)
Glitch.com (opens new window) project or account

Sample code

Okta Event Hook: Display Deactivated Users (opens new window)

About event hook implementation

Event hooks are outbound calls from Okta that notify your own applications of events occurring in your Okta org. See Event hooks for an overview.

Setting up an event hook in your Okta org requires the following generic steps:

Implement your external web service to receive event hook calls from Okta.
Register the endpoint of your external service with Okta and configure event hook parameters.
Verify to Okta that you control the endpoint.
Begin receiving ongoing delivery of event notifications.

The following event hook example uses the Okta event for a user deactivation. When this event occurs, the example external service code receives an Okta request. The external service responds with an acknowledgment to Okta that the request has been received, and displays the deactivated user's name to the console.

Tip: For another look at an event hook implementation, see the following developer experience blog example by Heather Wallander, Build Easy User Sync Webhooks with Okta (opens new window).

Set up the sample external service

This guide uses the website Glitch.com (opens new window) to act as an external service and to implement the event hook with an Okta org. See the following Glitch project to remix (copy) a working code example that implements an event hook when a user is deactivated: Okta Event Hook: Display Deactivated Users (opens new window).

Review the following sections to understand how to receive and parse the event hook call. Or use the code snippets to create the project on your own. If you copy the project, you can go directly to the section Enable and verify the event hook, which completes the setup.

Note: The sample application uses Basic Authentication. Ensure that you add the authentication credentials to the environment variables in the sample application's .env file. See HTTP Basic Authentication.

Configure initial event hook verification

Okta event hooks require an initial verification of the external service endpoint before the ongoing triggering of the hook. For more information on this request, see One-Time Verification Request.

Add the following code to your external service to receive and respond to this one-time verification request.

Note: Also, make sure to have the required default code and packages in your project. See Common hook set-up steps for further information.

The value userDeactivated is the endpoint in this example.


// Event hook initial verification
// Extract header 'x-okta-verification-challenge' from Okta request
// Return value as JSON object verification

app.get("/userDeactivated", (request, response) => {
  var returnValue = {
    "verification": request.headers['x-okta-verification-challenge'],
  };
  console.log("Event hook verification request received.")
  response.json(returnValue);
});

Parse the event hook request

Your external service receives the event hook request from Okta after a user is deactivated. Your external service must parse the event object of the request to determine the username or other data required by your external service.

In this example, after parsing the event hook request, the code displays the deactivated user to the console, and then replies to Okta with an empty, successful response (200).


//userDeactived event request, POST from Okta

app.post("/userDeactivated", (request, response) => {
  console.log(" ");
  console.log('The user ' + request.body.data.events[0].target[0]["alternateId"] + " has been deactivated on the Okta org!");
  response.sendStatus(200);

  }
)

Examine the event hook object

The JSON body sent as part of the Okta request includes the properties accessed in this example, namely target and alternateId. To see this or other event objects, call your Okta org with the System Log API (opens new window), using the specific event type as a filter parameter (opens new window). For example:

https://{yourOktaDomain}/api/v1/logs?filter=eventType eq "user.lifecycle.deactivate"

{
        "actor": {
            "id": "00u2di94bAMSEPvAY1d6",
            "type": "User",
            "alternateId": "okta.trainer@okta.com",
            "displayName": "Okta Trainer",
            "detailEntry": null
        },
        "client": {
            "userAgent": {
                "rawUserAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/86.0.4240.198 Safari/537.36",
                "os": "Mac OS X",
                "browser": "CHROME"
            },
            "zone": "null",
            "device": "Computer",
            "id": null,
            "ipAddress": "174.89.174.56",
            "geographicalContext": {
                "city": "Toronto",
                "state": "Ontario",
                "country": "Canada",
                "postalCode": "M6B",
                "geolocation": {
                    "lat": 43.7114,
                    "lon": -79.4462
                }
            }
        },
        "authenticationContext": {
            "authenticationProvider": null,
            "credentialProvider": null,
            "credentialType": null,
            "issuer": null,
            "interface": null,
            "authenticationStep": 0,
            "externalSessionId": "102lMcfHbwSTuS5V1oPHJs3lw"
        },
        "displayMessage": "Deactivate Okta User",
        "eventType": "user.lifecycle.deactivate",
        "outcome": {
            "result": "SUCCESS",
            "reason": null
        },
        "published": "2020-11-16T18:15:12.862Z",
        "securityContext": {
            "asNumber": 577,
            "asOrg": "example",
            "isp": "exampleISP",
            "domain": "example.com",
            "isProxy": false
        },
        "severity": "INFO",
        "debugContext": {
            "debugData": {
                "requestId": "X7LBsMxeqO-ADcGcmp0WGQAAB@g",
                "requestUri": "/admin/user/deactivate/00u3m90rxKjGQ0G6L1d6",
                "threatSuspected": "false",
                "url": "/admin/user/deactivate/00u3m90rxKjGQ0G6L1d6?"
            }
        },
        "legacyEventType": "core.user.config.user_deactivated",
        "transaction": {
            "type": "WEB",
            "id": "X7LBsMxeqO-ADcGcmp0WGQAAB@g",
            "detail": {}
        },
        "uuid": "ab62c0bc-2837-11eb-9823-9fb8f750c5a9",
        "version": "0",
        "request": {
            "ipChain": [
                {
                    "ip": "174.89.174.56",
                    "geographicalContext": {
                        "city": "Toronto",
                        "state": "Ontario",
                        "country": "Canada",
                        "postalCode": "M6B",
                        "geolocation": {
                            "lat": 43.7114,
                            "lon": -79.4462
                        }
                    },
                    "version": "V4",
                    "source": null
                }
            ]
        },
        "target": [
            {
                "id": "00u3m90rxKjGQ0G6L1d6",
                "type": "User",
                "alternateId": "john.doe@example.com",
                "displayName": "John Doe",
                "detailEntry": null
            }
        ]
    }

Enable and verify the event hook

Set up and verify the event hook within your Admin Console.

Note: If your org is set up to use the self-service Early Access (EA) feature event hook filtering, the event hook set up flow is slightly different. Follow the procedure in Create an event hook with the same values. To enable this feature, see Manage Early Access and Beta features.

Set up the event hook

Sign in to your Okta org (opens new window).
From the Admin Console, go to Workflow > Event Hooks.
Click Create Event Hook. The Add Event Hook Endpoint dialog box opens.
In the Name field, add a unique name for the hook (in this example, "Deactivated User Event Hook").
In the URL field, add your external service URL, including endpoint. For example, use your Glitch project name with the endpoint: https://your-glitch-projectname.glitch.me/userDeactivated.
Add the Authentication field and Authentication secret values. This example uses HTTP Basic Authentication.
- Authentication field = authorization
- Authentication secret = Basic YWRtaW46c3VwZXJzZWNyZXQ=
In the REQUESTS section of the dialog box, subscribe to the event type you want to monitor. In this example, a user deactivated in the Okta org: User deactivated.
Click Save & Continue.
You can complete the one-time verification Okta call now or verify the event hook later. If you're using the Glitch example, proceed to verification.

Note: You can also set up an event hook using an API. See Event Hooks Management (opens new window).

Verify the event hook

Verify the event hook to prove that your external service controls the endpoint. See One-Time Verification Request.

To complete the one-time verification of the event hook:

After creating the event hook, and if your external service is ready to handle the request, click Verify to complete the one-time verification step.

After ensuring that your external service is ready for the verification call, go Workflow > Event Hooks, click the Actions dropdown menu of any UNVERIFIED event hook, and select Verify.

The event hook now has a status of VERIFIED and is ready to send event hook calls to your external service.

Preview and test the event hook

The external service example is now ready with code to receive and respond to an Okta call. The Okta org is ready to call the external service when an event triggers. In this example, the event triggers when a user is deactivated in the Okta org.

Preview

To run a preview call of your event hook, sign in to your Okta org as the super admin.

In the Admin Console, go to Workflow > Event Hooks.
Locate the event hook that you created during the set-up step. In this example, select Deactivated User Event Hook or the name you gave the event hook.
Click the Actions menu for this hook, and select Preview.
In the Configure Event Hook request section, select an event from the Event Type dropdown menu. In this example, there's only one: User deactivated (user.lifecycle.deactivate).
Select a previous recent event (in this case, a user deactivation) from the System Log Event dropdown menu. The Preview & Deliver Event Hook section populates the JSON body of the event hook. If no event is available, the JSON body populates with sample data.

If no event data is available, you need to populate the JSON body of the preview with the target object. Click Edit and add data similar to:

"target": [
        {
            "id": "00u3m90rsKgGQ0G6L1d76",
            "type": "User",
            "alternateId": "john.doe@example.com",
            "displayName": "John Doe",
            "detailEntry": null
        }
    ]

Optionally, click Edit to modify the JSON body call for other testing scenarios.
Go to your Glitch application and open the log console (Tools > Logs). Ensure that your application is listening for requests.
Click Deliver Request. The event hook preview displays the status request as either successful or a failure. Check your Glitch application console. The following message should appear if successful:

The user john.doe@example.com has been deactivated on the Okta org!

Test

To run a test of your event hook:

Start by going to your Glitch application and opening the log console (Tools > Logs). Ensure your application is listening for requests.
In your Okta org, sign in as an administrator and create a test user in the Admin Console.
- Go to Directory > People, and click Add Person.
- As an example, add the user John Doe as seen from the Event object sample code.
For this user, select the User's profile by clicking John Doe's name.
Click the More Actions dropdown menu, and select Deactivate.
Confirm the deactivation.
Navigate back to your Glitch application's log console. You should see the following output to the console:

The user john.doe@example.com has been deactivated on the Okta org!

Note: Review the troubleshooting section for information if you encounter any setup or configuration difficulties.

Next steps

Review the following guides to implement other inline hook examples:

On this page