> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Entra ID Webhook Setup Guide

> Configure Microsoft Entra ID to deliver events to StackOne.

## Prerequisites

The connector should already be set up, with a Connector Profile and a Linked Account. See [Getting Started](/connectors/microsoftentraid#getting-started) on the Microsoft Entra ID connector page.

<section data-guide-section data-guide-scopes="">
  <h2>How StackOne sets up Microsoft Entra ID webhooks</h2>

  <p>Nothing needs configuring in Microsoft Entra ID. When you connect an account with events enabled, StackOne creates a Microsoft Graph change-notification subscription for each enabled event automatically and deletes it again when the connection is removed. Each subscription covers every user or group in the directory.</p>

  <Steps>
    <Step title="Check the directory permissions are granted">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>A user subscription needs `User.Read.All` and a group subscription needs `Group.Read.All`, the same permissions the connector already uses to list users and groups. No webhook-specific permission has to be added.</p>

        <ul>
          <li>If the connection can list users and groups today, it can receive their webhooks.</li>
          <li>A connection whose custom scopes leave out one of these permissions cannot create that subscription, so its events are never delivered.</li>
        </ul>
      </div>
    </Step>

    <Step title="Connect the account again when the subscriptions expire">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Microsoft Graph expires user and group subscriptions after at most 29 days, and StackOne does not renew them. Delivery stops silently when a subscription lapses; no error is raised.</p>

        <ul>
          <li>Reconnect the account to create fresh subscriptions and resume delivery.</li>
          <li>Reconnecting also removes the previous subscriptions, so no duplicates are left behind.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available webhook events</h2>

  <p>Microsoft Entra ID emits events for users and groups across the whole directory. Only events selected in StackOne are delivered, because StackOne creates a Microsoft Graph subscription only for those.</p>

  <Steps>
    <Step title="Keep the validation check enabled (required)">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Microsoft Graph verifies the notification URL before it creates each subscription, and the subscription is refused if the check is not answered.</p>

        <ul>
          <li><strong>Validation Check</strong> (`webhook_validation_check`) — Answers Microsoft Graph's validation request when a subscription is created. <strong>Must be enabled</strong>; without it no subscription can be created and no other event is delivered.</li>
        </ul>
      </div>
    </Step>

    <Step title="Enable user events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events covering users in the directory. Microsoft Graph reports a new user, a changed user, a soft-deleted user and a restored user as the same change, so they share one event.</p>

        <ul>
          <li><strong>User Updated</strong> (`user_updated`) — Fired when a user is created, changed, moved to deleted items, or restored</li>
          <li><strong>User Deleted</strong> (`user_deleted`) — Fired when a user is permanently deleted</li>
        </ul>
      </div>
    </Step>

    <Step title="Enable group events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events covering groups in the directory, including their membership.</p>

        <ul>
          <li><strong>Group Updated</strong> (`group_updated`) — Fired when a group is changed, has members added or removed, is moved to deleted items, or is restored. A newly created group may raise no notification</li>
          <li><strong>Group Deleted</strong> (`group_deleted`) — Fired when a group is permanently deleted</li>
        </ul>
      </div>
    </Step>

    <Step title="Enable subscription lifecycle notifications">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Notifications about the subscriptions themselves rather than about directory changes.</p>

        <ul>
          <li><strong>Subscription Lifecycle Notification</strong> (`subscription_lifecycle_notification`) — Fired when Microsoft Graph reports that a subscription must be reauthorized, has been removed, or missed notifications</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Delivery format</h2>

  <p>Details of how Microsoft Graph delivers events to StackOne.</p>

  <Steps>
    <Step title="Retrieve the record to see what changed">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>A notification identifies what changed rather than carrying it. Each one holds the id of the user or group, so read the full record with <strong>Get User</strong> or <strong>Get Group</strong> when you need its contents.</p>

        <ul>
          <li>Group membership changes list the affected member ids under `members@delta` in the notification's `resourceData`; an entry that carries `@removed` is a member who was removed.</li>
          <li>A user or group that was moved to deleted items can no longer be read with <strong>Get User</strong> or <strong>Get Group</strong>.</li>
        </ul>
      </div>
    </Step>

    <Step title="Expect batched notifications">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Microsoft Graph can send several notifications in one request. StackOne splits the batch and delivers each notification as its own event.</p>
      </div>
    </Step>

    <Step title="Make processing idempotent">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Microsoft Graph delivers at least once and retries a failed delivery for up to four hours, so the same notification can arrive more than once.</p>

        <ul>
          <li>Treat each notification as a signal to re-read the user or group rather than as a change log.</li>
          <li>Make processing idempotent on the user or group id so a repeated notification is harmless.</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.