Instructions for

On this page

Event Hooks with ngrok

Instructions for

This guide provides a working 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

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:

  1. Create a local application or use an existing application.
  2. Run the ngrok utility with your local application.
  3. Create an Event Hook.
  4. Preview and test the Event Hook.

Create a local application

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).

Some installation notes:

  • You don't need to have an account to install and run ngrok, but creating a free account provides more features as well as basic authentication.
  • You can install ngrok directly in your project folder, sample-app, as documented from the ngrok download page. Or you can install on your system's path directory to be able to run ngrok from any folder. Alternatively, you can install the executable in your favorite local folder, but you'll need the folder path when referencing 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 folder, sample-app, run the following command in your terminal:

sample-app > ./ngrok http 8082

or if you installed in your system path:

sample-app > ngrok http 8082

or if you used your favorite folder:

sample-app > ~/applications/ngrok http 8082

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

A screen shot 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. You'll 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.

A screen shot of the ngrok web interface that includes the response body, header, and other details.

Create an Okta Event Hook

Create the Okta Event Hook to work with your local application, which can now be exposed externally. The Event Hook must be set up and verified within your Okta Admin Console.

Set up the Event Hook

  1. Sign in to your Okta org (opens new window).

  2. From the Admin Console, go to Workflow > Event Hooks.

  3. Click Create Event Hook. The Add Event Hook Endpoint dialog box opens.

  4. In the Name field, add a unique name for the Hook (in this example, "New User Event Hook").

  5. 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.

  6. Include the Authentication field and Authentication secret values. In this example, our server.js code uses Basic Authentication:

    • Authentication field = authorization

    • Authentication secret = Basic YWRtaW46c3VwZXJzZWNyZXQ=

  7. 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.

  8. Click Save & Continue.

  9. With your ngrok session and local application running, complete the one-time verification Okta call at this time. 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.

To complete the one-time verification of the Event Hook:

  • After creating the Event Hook, and if your ngrok session and local application are ready to handle the request, click Verify to complete the one-time verification step.

or

  • After making sure that your ngrok session and local application are ready for the external verification call, 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 your local application is working 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, as well as 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:

  1. Ensure that both your ngrok session and local sample application are running.

  2. 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
      • User Name: john.doe@example.com
  3. 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!

  4. 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. Clicking Replay on the ngrok inspection interface replays the event hook call to assist in development. See Replay the Event Hook.

    A screen shot of the ngrok inspection interface that includes details of a call.

Preview the Event Hook

To run a preview call of your Event Hook:

  1. In the Admin Console, go to Workflow > Event Hooks.

  2. Locate the Event Hook you created during the set-up step. In this example, select New User Event Hook or the name you gave the Event Hook.

  3. Click the Actions menu for this hook, and select Preview.

  4. In the Configure Event Hook request section, select an event from the Event Type dropdown menu. In this example, there is only one: User Created (user.lifecycle.create).

  5. 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 are 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"}]
  6. 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.

  7. 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!

  8. 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.

    A screen shot of the ngrok inspection interface that includes details of a call.

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:

  1. In the ngrok inspection interface (http://localhost:4040), select an Event Hook from Okta.

  2. Click Replay > Replay with modifications:

  3. Optionally, modify the request body with a different content. For example: "target": [{ "alternateId": "jane.doe@example.com"}]

  4. Click Replay.

  5. Your local application receives the modified request to process and provide a response.

See also ngrok Documentation (opens new window).

See also

For background conceptual information on Event Hooks, see Event Hooks.