Instructions for

On this page

Event hooks with Hookdeck

This guide provides a working example of an Okta event hook that uses the Hookdeck utility.


Learning outcomes

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

What you need

Sample code


About event hooks with Hookdeck

Event hooks are outbound calls from Okta that can notify your own software systems of events that occur in your Okta org. The Hookdeck utility exposes a local application to the internet and receives and responds to event hook calls. The Hookdeck utility enables the testing of event hooks locally, rather than implementing an internet-based production or test external service.

Create a local application

Install Hookdeck

If you already have Hookdeck installed, move on to Run Hookdeck. If not, follow the installation instructions at Using The Hookdeck CLI (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 Hookdeck, but creating a free account provides more features as well as API authentication.

Run Hookdeck

After installing Hookdeck, start a session to forward your event hooks to a local port (1337 in this example). Run the following command in your terminal:

nodejs-webhook-server-example> hookdeck listen 1337

Complete the following interactive session to define the information about the Hookdeck session:

  • What should your new source label be?

    Enter: okta

  • What path should the webhooks be forwarded to (i.e.: /webhooks)?

    Enter: /okta-webhooks-endpoint

  • What's the connection label (i.e.: My API)?

    Enter: My Okta Response Server

With this data, Hookdeck creates a session and URL to use for sending requests. If you see the following content in your terminal, Hookdeck is running successfully:

A screen shot of a terminal that displays a Hookdeck session status. The session status contains urls that tunnel into the local port.

Note: You'll use the Webhook URL that is available from the Hookdeck terminal session when setting up your event hook. For example, https://events.hookdeck.com/e/src_jHlvbIjGsgY2xhYZeCGxohK4.

See Hookdeck (opens new window) or their Product docs (opens new window) for further information.

Review Hookdeck dashboard

The Hookdeck dashboard provides an opportunity to review all calls to your local application. See Browsing Events (opens new window) for details on using this interface. With the Hookdeck utility running, use the guest account Login URL to access details on your hook calls. For example, your initial guest account URL appears similar to: https://api.hookdeck.com/signin/guest?token=5sszlk2ndmkp5puy07uixrqtatkzvhwc13gctx9o3gmgczcrfu.

Each call to your local application appears in the dashboard and includes the response body, header, and other details:

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

Hookdeck development workflow

Hookdeck URLs are reusable and permanent (when you create a free account) and serve the entire development lifecycle—from development to staging to production. See Development Workflow (opens new window) for more information on using Hookdeck.

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 from Hookdeck. For this example, use the Webhook URL highlighted after running Hookdeck. See Run Hookdeck. For example, your URL should appear similar to: https://events.hookdeck.com/e/src_s8lCGfojGBPj8L0lszAZl6fD.

    Note: Hookdeck generates the URL when creating the session and incorporates the local application's hook endpoint as part of the unique URL. That is, the endpoint is not explicitly defined as part of the URL.

  6. Leave the Authentication field and Authentication secret values blank in this example.

    However, to add Basic Authentication, add the application code that is required at Add Basic Authorization and Body Parsing and then enter the following values for those fields:

    • Authentication field = authorization

    • Authentication secret = Basic YWRtaW46c3VwZXJzZWNyZXQ=

  7. In the REQUESTS section of the dialog box, subscribe to the Event Type that you want to monitor. In this example, the Event Type is User created for a user created in the Okta org.

  8. Click Save & Continue.

  9. Complete the one-time verification Okta call at this time by clicking Verify. You can also verify the event hook at later time. See Event hook verification.

Event hook verification

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

Note: Hookdeck includes the capability to verify your endpoint, and no code is necessary for your local application.

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

  • After creating the event hook, click Verify to complete the one-time verification step.

or

  • 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 local application through Hookdeck.

Preview, test, and review the event hook

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

Preview

To run a preview call of your event hook:

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

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

  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 drop-down menu. In this example, there is only User Created (user.lifecycle.create).

  5. The most recent event populates the Preview & Deliver Event Hook section with the JSON body of the event hook if there is one. If no event is available, the JSON body populates with sample data.

  6. Ensure that both your Hookdeck session and local sample application are running.

  7. Click Deliver Request. The Event Hook Preview displays the status request as either successful or a failure. Review your local application console to view the output of the event hook body. For example:

    A screen shot of the application terminal with response body output to the console.

  8. Review your Hookdeck terminal output for a line item reference to the specific call and a unique dashboard URL to the details on the call.

    A screen shot of the Hookdeck terminal with response line item output to console.

  9. Review your Hookdeck dashboard (https://dashboard.hookdeck.com/cli/events). Each call recorded by Hookdeck appears in the interface from which you can review the complete call response body, header, and other details.

    A screen shot of the Hookdeck dashboard that includes body details.

Test

To run a test of your event hook:

  1. Ensure that both your Hookdeck 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 Jane Doe with the following fields:
      • First Name: Jane
      • Last Name: Doe
      • User Name: jane.doe@hookdeckexample.com
  3. Click Save to create a new user. The new user triggers an event hook call.

  4. Navigate back to your local application's console. The request body for this call appears in the console, as designed by the local application code.

  5. Review your Hookdeck terminal output for a line item reference to the specific call and a unique dashboard URL to the details on the call.

  6. Review the unique dashboard URL (for example, https://dashboard.hookdeck.com/cli/events/evt_x3H5QdAL2JGvxMbvqcvwK8UF). Scroll to the Body section and open the "Root" > "Data" sections. Your new user's name and username appear under the "target" property.

A screen shot of the Hookdeck dashboard that includes body details.

See also

See Event hooks for background conceptual information on event hooks.