Build an Okta Workflow for group membership change events

TL;DR — Build an event-triggered Okta Workflow using the group membership event as the trigger, then branch on the event type for add vs remove and map the payload fields you actually need. The most common failure is subscribing to the wrong event or testing with a group rule, then wondering why no flow run appears. Reading time: ~5 min

Goal

When you finish, Okta will automatically start a Workflow every time a user is added to or removed from a group, and you will be able to verify the run history shows the event payload with the user ID, group ID, and event type.

Prerequisites

• Okta tenant with admin access that can create Workflows and manage event subscriptions
• Okta Workflows enabled in your tenant
• A test user and a test group already created in Okta
• Permission to add and remove the test user from the test group
• A browser session with access to the Okta Admin Console
• Optional for downstream testing: a webhook endpoint you control, or a request bin URL
• The exact identifiers to keep handy:
  • test user login/email
  • test group name
  • any downstream URL if you will post the event out of Okta

Steps

Step 1: Create a dedicated test group and test user if you do not already have them

Use the Okta Admin Console menu paths:

Directory → Groups → Add group

Enter these literal values:

Name: wf-group-membership-test
Description: Triggers Okta Workflow tests for membership changes

Then create a user if needed:

Directory → People → Add person

Enter values like:

First name: Workflow
Last name: Tester
Username: workflow.tester@example.com
Primary email: workflow.tester@example.com

What you should see: the group wf-group-membership-test exists and the user appears in Directory → People.

Step 2: Create the Workflow flow with the group membership event trigger

Open the Workflows console from your Okta admin area, then create a new flow:

Workflows Console → Flows → New Flow

Use this literal name:

React to group membership changes

Add an event trigger card. In the trigger picker, search for the Okta event for group membership changes and select the event trigger for user added to group / user removed from group. If your tenant presents separate event options, add the one for group membership changes and create branching in the next step.

Use this exact menu path pattern in the flow builder:

Add card → Okta → Event trigger → Group membership event trigger

What you should see: the flow starts with an event trigger card showing fields for the event payload and the flow status is editable.

Step 3: Add a branch for add vs remove events

After the trigger card, add a conditional card:

Add card → Flow Control → If/Else

Set the condition to compare the incoming event type field to the add event type. Use the event type field exposed by your trigger card. The literal values to compare against are:

group.user_membership.add
group.user_membership.remove

If your trigger exposes the raw Okta event type string instead of normalized labels, branch on the exact event type string shown in the trigger output panel. In many tenants, the event card preview lets you inspect the payload schema before the first live run.

What you should see: one branch for add and one branch for remove, each with a clear condition based on the event type field.

Step 4: Add a visible action so you can prove the flow ran

Do not start with a complex downstream integration. First add a simple action that records the event. The most practical option is to send the payload to a webhook collector you control.

Add a webhook/API action card:

Add card → HTTP → Custom API Action

Populate it with literal values like these:

{
  "method": "POST",
  "url": "https://webhook.site/your-unique-id",
  "headers": {
    "Content-Type": "application/json"
  },
  "body": {
    "eventType": "{{trigger.eventType}}",
    "userId": "{{trigger.user.id}}",
    "userLogin": "{{trigger.user.profile.login}}",
    "groupId": "{{trigger.group.id}}",
    "groupName": "{{trigger.group.profile.name}}",
    "published": "{{trigger.published}}"
  }
}

If your trigger exposes different field names, drag the fields from the trigger output panel instead of typing them. Keep the JSON keys exactly as shown so verification is easy.

What you should see: the HTTP card validates, and the request body fields are mapped from the trigger output.

Step 5: Turn the flow on

In the flow editor, enable the flow:

Flow editor → Save
Flow editor → Turn on

If your tenant requires event subscription confirmation, complete it in the prompt shown by the trigger card.

What you should see: the flow status changes to On or Running, and the trigger card no longer shows draft-only warnings.

Step 6: Generate a real membership change event

In the Okta Admin Console, add the test user to the test group:

Directory → Groups → wf-group-membership-test → Manage people → Add users

Select:

workflow.tester@example.com

Then click:

Save

After the add event is processed, remove the same user from the same group:

Directory → Groups → wf-group-membership-test → Manage people → Remove from group

What you should see: the group membership list updates immediately in the UI, and within a short delay the Workflow run history shows one run for add and one run for remove.

Verify it works

Check the Workflow run history first:

Workflows Console → Flows → React to group membership changes → History

Expected result:

Two successful runs
- one with eventType = group.user_membership.add
- one with eventType = group.user_membership.remove

If you posted to a webhook collector, verify the payload arrived. A successful payload shape should look like this:

{
  "eventType": "group.user_membership.add",
  "userId": "00u123example",
  "userLogin": "workflow.tester@example.com",
  "groupId": "00g123example",
  "groupName": "wf-group-membership-test",
  "published": "2026-08-05T14:22:31.000Z"
}

If your downstream endpoint is your own service, check for an HTTP 2xx in the action card output. A failure usually looks like this:

Status code: 401
Response body: {"error":"unauthorized"}

or:

Status code: 404
Response body: Not Found

The end-to-end proof is: membership changed in Okta, flow history shows a successful run, and the downstream action received the expected user and group identifiers.

Common pitfalls

Triggering on the wrong event

Mistake: selecting a generic user update event instead of the group membership event.

Symptom: the flow runs for profile edits but not when users are added to or removed from groups.

Fix: replace the trigger with the dedicated group membership event trigger and branch on group.user_membership.add and group.user_membership.remove.

Testing with group rules instead of direct membership changes

Mistake: expecting the same timing and payload when a rule or import changes membership.

Symptom: no immediate run appears, or the event shape differs from what you mapped.

Fix: first test with a manual add/remove in Directory → Groups → Manage people; only after that validate rule-driven scenarios in your tenant.

Flow is saved but not turned on

Mistake: leaving the flow in draft/off state.

Symptom: membership changes happen in Okta, but the flow history stays empty.

Fix: open the flow and click Turn on; then repeat the add/remove test.

Mapping fields that do not exist in your trigger output

Mistake: typing payload paths from memory, such as trigger.user.login, when your card exposes trigger.user.profile.login.

Symptom: the HTTP action runs with blank fields or card validation errors.

Fix: delete the hand-typed tokens and drag the fields from the trigger output panel into the body.

Downstream webhook rejects the request

Mistake: posting JSON without the expected auth header or to the wrong path.

Symptom: the flow run exists, but the action card shows 401 Unauthorized, 403 Forbidden, or 404 Not Found.

Fix: update the HTTP card with the exact URL and required headers, then replay the event by removing and re-adding the test user to the group.

Assuming event delivery is synchronous

Mistake: refreshing once and concluding the trigger is broken.

Symptom: the group membership UI updates immediately, but the Workflow history appears a short time later.

Fix: wait a minute, then refresh the flow history; if still empty, verify the flow is on and the correct trigger is selected.

This article was written by an AI system and published pending human review. Verify anything you intend to act on.