Instructions for

Event hooks with ngrok

Instructions for

This guide provides a functional example of an Okta event hook that uses the ngrok utility.

Learning outcomes

Understand the Okta event hook calls and responses.
Implement Okta event hooks using a local application and the ngrok utility.
Preview and test an Okta event hook and review the call details with ngrok.

What you need

Okta Developer Edition organization (opens new window)
A local application. See Create a local application in this guide for a simple example.
ngrok

Sample code

See Create a local application for this project's sample code.

About event hooks with ngrok

Event hooks are outbound calls from Okta that can notify your software systems of events that occurred in your Okta org. The ngrok utility exposes local applications to the internet and receives and responds to event hook calls. This setup enables the development and testing of event hooks locally, rather than using an external test or production environment. The ngrok utility also provides a replay function to assist you in testing and developing your external service code.

To use this guide:

Create a local application or use an existing application.
Run the ngrok utility with your local application.
Create an event hook.
Preview and test the event hook.

Create a local application

To get you up-and-running quickly, follow the steps below to build a very basic Express Node.js application. This application serves up a web page and responds to Okta event hook calls.

The event hook use case is a simple local application response to the addition of a new Okta user.

Create a folder and initialize the project

Create a local folder to hold your sample application and open it. In this example, sample-app.
```
>sample-app
```
Initialize a default package.json file. Accept the default values for all questions after running the command.
```
>npm init --yes
```

Install the package dependencies, express, express-basic-auth, and body-parser.

>npm install express
>npm install express-basic-auth
>npm install body-parser

Create the index and web server code

In the same sample-app directory, create an index page, index.html, as follows, which launches when running the application:

<html>
<head>
<meta charset="utf-8" />
<title>Simple Test Application</title>
</head>
<body>
<h1>Congratulations, your simple test application is working.</h1>
<p>See the following links for more information:
<ul>
    <li><a href="https://developer.okta.com/docs/concepts/event-hooks">
    Event hook concepts</a></li>
    <li><a href="https://developer.okta.com/docs/guides/event-hook-implementation/">
    Event hook guides</a></li>
</ul>
</p>
</body>
</html>

Add the server page, server.js, that contains the simple application code and an endpoint for the Okta event hook.

The endpoint you call from Okta is /userCreated.

var express = require('express');
var app = express();

var bodyParser = require("body-parser");
app.use(bodyParser.json());


app.get('/', function (request, response) {
    response.sendFile(__dirname + '/index.html');
});

//Basic Auth
var basicAuth = require('express-basic-auth');
app.use(basicAuth({
users: { 'admin': 'supersecret' },
unauthorizedResponse: req => 'Unauthorized'
}));


// Event hook initial verification
// Extract header 'x-okta-verification-challenge' from Okta request
// Return value as JSON object verification
app.get("/userCreated", (request, response) => {
    var returnValue = {
    "verification": request.headers['x-okta-verification-challenge'],
    };
    response.json(returnValue);
});

//userCreated Event request, POST from Okta

app.post("/userCreated", (request, response) => {

    var newUser = request.body.data.events[0].target[0]["alternateId"];
    console.log(" ");
    if (newUser == null){
        console.log('No user in request! Update the JSON target field with a value.');
    } else {
        console.log('The user ' + newUser +
        ' has been added to the Okta org!');
    }
    response.sendStatus(200);
   }
);

var server = app.listen(8082, function () {
    console.log('Node server is running on http://localhost:8082');
});

Run the sample application

From the project directory:
```
>node server.js
```
From your browser, navigate to your local port, in this example 8082, to see the index.html page:

http://localhost:8082

If your web page deploys, the simple application is working, and ready for your event hook set up.

A screen shot of the simple application web page that includes a welcome message and links to the Okta Developer documentation.

Install ngrok

If you already have ngrok installed, move on to Run ngrok. If not, follow the installation instructions at https://ngrok.com/download (opens new window) to install in your sample application folder (or the location of your choice).

Installation notes:

A free ngrok account isn't required, but can provide additional features including basic authentication.
You can install ngrok in the system path directory or the project directory. Alternatively, you can install the executable in another local directory, as long as you reference the directory path when using the tool.

Run ngrok

After installing ngrok, ensure that it's running by creating a "tunnel" into a local port (8082 in this example). If you installed directly into your project directory (for example, sample-app), run the following command in your terminal:

sample-app > ./ngrok http 8082

If you see the following content in your terminal, ngrok is running successfully:

An image of a terminal that displays an ngrok session status, with online in green. The session status contains urls that tunnel into the local port.

Note: Copy the forwarding URL that is available from the ngrok terminal session. For example: https://2d20-142-126-163-77.ngrok.io. Use this URL when setting up your Okta event hook.

See ngrok (opens new window) or their documentation (opens new window) for further information.

Review ngrok inspection interface

The ngrok inspection interface provides an opportunity to review all calls to your local application. See ngrok documentation (opens new window) for details on using this interface. With the ngrok utility running, open the following URL in a browser: http://localhost:4040.

Each call to your local application appears in the interface and includes the response body, header, replay functionality, and other details. Proceed to the following sections to see an example request.

An image of the ngrok inspection interface that includes details of a call.

Create an Okta event hook

Create the Okta event hook to work with your local application, which can now be exposed externally. You must configure 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, "New user event hook").
In the URL field, add your external service URL. For this example, add the code endpoint, /userCreated from server.js to the end of the https:// URL from the ngrok session. For example: your URL should appear similar to: https://2d20-142-126-163-77.ngrok.io/userCreated.
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 created in the Okta org: User created.
Click Save & Continue.
With your ngrok session and local application running, complete the one-time verification Okta call now. You can also verify the event hook later.

Verify the event hook

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

If you didn't verify the hook during the Create the event hook procedure, ensure that your ngrok session and local application are ready for the external verification call, and go to the Event Hooks table, click the Actions dropdown menu of your UNVERIFIED event hook, and select Verify.

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

Note: A successful event hook verification also indicates that your local application is usable with the ngrok session. Review the ngrok terminal or inspector interface for details on the first GET call to your local application.

Test, preview, and review the event hook

With your local application now exposed externally through an ngrok session, you can test and preview Okta event hook calls, and review details of the calls using the ngrok inspection interface. The Okta org is also set up to call your local application when an event is triggered. In this example, the event is triggered when a user is added to your Okta org.

Test the event hook

To run a test of your event hook:

Ensure that both your ngrok session and local sample application are running.
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 with the following fields:
  - First name: John
  - Last name: Doe
  - Username: john.doe@example.com
Navigate back to your local application's console. If the event hook was successful, the following message appears:

The user john.doe@example.com has been added to the Okta org!
Check your ngrok inspection interface (http://localhost:4040). Each call recorded by ngrok appears in the interface from which you can review the complete call response body, header, and other details. See Review ngrok inspection interface. Click Replay on the ngrok inspection interface to replay the event hook call to assist in development. See Replay the event hook.

Preview the event hook

To run a preview call of your event hook:

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 New 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, the only available option is: User Created (user.lifecycle.create).
The most recent event (in this case, user John Doe created previously) populates the Preview & Deliver Event Hook section with the JSON body of the event hook. You can also select an older event from the System Log Event dropdown menu. If no event is available, the JSON body populates with sample data.
Note:
- The preview event hook JSON body can be modified for testing or development purposes. Click Edit to update the "target" field, for example.
- If you're using the preview sample data, you must edit the preview to add a target value. Include an email address for the alternateId property. For example: "target": [{ "alternateId": "john.doe@example.com"}]
Ensure that both your ngrok session and local sample application are running.

Note: If you start a new ngrok session at any time, make sure to update the event hook URL.
Click Deliver Request. The Event Hook Preview displays the status request as either successful or a failure. Check your local application console. The following message appears if successful:

The user john.doe@example.com has been added to the Okta org!
Check your ngrok inspection interface (http://localhost:4040). Each call recorded by ngrok appears in the interface from which you can review the response body, header, and other details. See Review ngrok inspection interface.

Replay the event hook

The ngrok inspection interface provides a replay function that you can use to test your code without reproducing test conditions in Okta. To replay your call:

In the ngrok inspection interface (http://localhost:4040), select an event hook from Okta.
Click Replay > Replay with modifications:
Optionally, modify the request body with a different content. For example: "target": [{ "alternateId": "jane.doe@example.com"}]
Click Replay.
Your local application receives the modified request to process and provide a response.

On this page