Guide on Okta Webhooks Features and Best Practices

Types of Event Hooks

Hooks are essentially outbound HTTP calls from Okta. They provide developers with the ability to add custom logic to Okta flows and integrate with third-party applications. There are two types of Hooks Okta provides:

• Inline Hooks — Inline hooks enable developers to interfere with an ongoing process flow and customize the flow. Inline hooks are synchronous and will pause the flow until it receives a response from the external service being used to extend Okta functionalities.
• Event Hooks — Unlike their inline counterparts, event hooks are asynchronous and does not pause nor interfere with any process flows. These are more commonly called “webhooks”

Prior to the introduction of event hooks by Okta, developers had to manually poll Okta’s system log API to know about the occurrence of a specific event. The event hook sends notifications once a specified event occurs in an organization .

Setting Up And Configuring An Event Hook

It is possible to create an Okta event hook either by using the management API or the admin console. We will discuss how to set up and configure a webhook using both methods below.

Configuring an Event Hook using the REST admin API

An event hook can be created by making an authenticated HTTP POST request to Okta’s /api/v1/eventHooks endpoint along with the information of the intended event hook to be created as the request body. A sample of a JSON request body for registering an event hook can be seen below

    {
      "name": "Name Of Event Hook",
      "events": {
        "type": "EVENT_TYPE",
        "items": ["user.lifecycle.create", "user.lifecycle.activate"]
      },
      "channel": {
        "type": "HTTP",
        "version": "1.0.0",
        "config": {
          "uri": "https://www.YOURSSLSECUREURLENDPOINT",
          "headers": [
            {
              "key": "X-Other-Header",
              "value": "some-other-value"
            }
          ],
          "authScheme": {
            "type": "HEADER",
            "key": "Authorization",
            "value": "${api-key}"
          }
        }
      }
    }

Within the request body, as seen above, we include all the parameters relevant to the event hook to be created in the body.

Configuring an Event Hook using the Admin Console

The alternative way to create an event hook is through Okta’s admin console UI. Once signed in, navigate to the Workflow > Event Hooks page and click Create Event Hook. Fill in the fields appropriately. The official documentation has more information about the fields you are expected to fill. It is important to note that event hooks can only be created and retrieved by super admins.

One-Time Verification Request

After registering an event hook, Okta requires that you verify that you have access to the URL endpoint you registered. This verification is a one-time GET request made by Okta to the URL endpoint you registered. The one-time verification request is an important step in setting up the event hook — If it is not completed successfully, the event hook will not send any notifications when the specified event is triggered.

To verify the Event Hook after its creation

Click verify to complete the one-time verification step. Okta will send a GET request to your external service. The request sent from Okta will include an X-Okta-Verification-Challenge header. Your external service should extract the value of the X-Okta-Verification-Challenge header and return it as a request body in JSON format, using “verification” as the keys.

    app.get("/webhook", (req, res) => {
      const HeaderValue = req.headers["x-okta-verification-challenge"];
      res.json(HeaderValue);
    });

In the code snippet seen above, we extract the x-okta-verification-challenge header received along with the request made by Okta to your service. After extracting the header value, we send the value in JSON format as a response to Okta. The purpose of this verification is to ensure that you have control over the endpoint you registered during the creation of the event hook.

Previewing Event Hooks

It is possible to preview Event Hooks before it is activated to see its contents, better helping you structure your code. You can view the JSON payload for a specific event type using the Okta admin console. You can have the payload delivered to your external service.

To preview your Event Hook, head over to the admin console, go to Workflow > Event Hooks. Select the webhook you would like to preview, click its actions menu & click preview.

Delayed Processing

Incoming Okta event hooks will timeout after 3 seconds. It is a good practice to respond to event hook notifications immediately they are received. The processing of the received notifications should be delayed or queued till after a response has been sent. Your service should send an HTTP request with a 2xx status code as a response to the incoming webhook. Any notification that is not responded to within 3 seconds will be logged as a failure.

Security

It is important to take precautionary measures to implement security of incoming webhooks. When configuring an Event Hook, It is possible to add an authentication header. If you provide an authentication string when creating the Event Hook, subsequent Event Hook notifications sent to your service will contain that string in the Authorization header as seen below.

    Accept: application/json
    Content-Type: application/json
    Authorization: ${SECRET_KEY_YOU_PROVIDED}

Your endpoint can extract the value of the Authorization header & compare it with the secret key you provided. To add a higher level of security to your Event Hooks, ensuring calls are coming from Okta, you can allowlist Okta IP addresses. A full list of Okta IP addresses can be found here. It is also important to note that only HTTPS URLs can be used when registering a new Event Hook

Debugging Event Hooks

Okta has a system log that records every event that occurs within your organization. Any notifications received from event hooks can be found in the system log. Using the system log API, you can periodically run reconciliation jobs to ensure no events are missed by your external service. When an error occurs with the Event Hook, it is recorded in the System Log in the form of event_hook.delivery.