Skip to main content

Notifications

When PIM Monitor detects changes, it can send notifications to email and webhooks. This is optional. Skip this page if you do not need notifications.

Email​

Requires:

  • A service principal with Mail.Send on Microsoft Graph
  • NOTIFICATION_EMAIL - recipient address
  • NOTIFICATION_MAIL_FROM - sender UPN (typically the service principal)

Setup​

  1. In the app registration, grant Mail.Send:

    • Go to API permissions > Add a permission > Microsoft Graph
    • Select Application permissions > Mail > Mail.Send
    • Grant admin consent

  2. Set pipeline variables:

    NOTIFICATION_EMAIL = security-team@contoso.com
    NOTIFICATION_MAIL_FROM = pim-monitor@contoso.onmicrosoft.com

Email format​

Rich HTML email with a severity summary bar and one collapsible <details> block per change. Each block shows the change description and an inline field-level diff (old value in red, new value in green). A "View diff" button links to the inventory commit in Azure DevOps or GitHub.

The email subject follows this pattern:

[PIM Monitor] 3 High, 7 Medium, 2 Low changes

Webhooks​

PIM Monitor auto-detects the webhook type from the URL and formats the payload accordingly.

Teams (Power Automate)​

Webhook URL pattern: https://outlook.webhook.office.com/webhookb2/...

The old O365 Incoming Webhook connector is deprecated. Use a Power Automate workflow instead.

Setup:

  1. In Power Automate, create a new flow with the trigger "When a Teams webhook request is received"
  2. Add a "Post card in a chat or channel" action to post the notification to a Teams channel
  3. Copy the HTTP POST URL generated by the trigger
  4. Set NOTIFICATION_WEBHOOK_URL to this URL

PIM Monitor detects webhook.office.com in the URL and sends a Teams Adaptive Card payload. For Power Automate URLs (e.g. logic.azure.com), the generic JSON payload is sent — use the Generic / custom option below and parse the payload in your flow.

Slack​

Webhook URL pattern: https://hooks.slack.com/services/...

Setup:

  1. Go to Workspace settings > Integrations > Incoming Webhooks
  2. Create a new webhook and choose a channel (e.g. #security)
  3. Copy the webhook URL
  4. Set NOTIFICATION_WEBHOOK_URL to this URL

Discord​

Webhook URL pattern: https://discord.com/api/webhooks/...

Setup:

  1. Go to Channel settings > Integrations > Webhooks
  2. Click Create Webhook
  3. Copy the webhook URL
  4. Set NOTIFICATION_WEBHOOK_URL to this URL

Custom / generic​

Any other URL receives a JSON payload:

{
  "text": "PIM Monitor — 12 change(s) detected",
  "summary": "...",
  "changesBySeverity": {
    "high": 3,
    "medium": 7,
    "low": 2,
    "informational": 0,
    "total": 12
  }
}

Severity threshold​

Set NOTIFICATION_MIN_SEVERITY to control when notifications fire:

NOTIFICATION_MIN_SEVERITY = High

Valid values: High, Medium, Low, Informational. Default is Medium. If there are no changes at or above the threshold, no notification is sent.

Testing webhooks locally​

. ./src/diff.ps1
. ./src/notifications.ps1

$mockChanges = @(
  @{ severity='High'; description='Policy rule changed: Enablement_EndUser_Assignment (Global Admin)' }
  @{ severity='Medium'; description='Policy rule changed: Expiration_EndUser_Assignment (Global Admin)' }
)
$grouped = Group-ChangesBySeverity -Changes $mockChanges

# Inspect the payload shape
$payload = Build-TeamsPayload -ChangesBySeverity $grouped
$payload | ConvertTo-Json

# Send to a real webhook
Send-WebhookNotification -ChangesBySeverity $grouped -WebhookUrl 'https://hooks.slack.com/services/...'

Disabling notifications​

Leave NOTIFICATION_EMAIL and NOTIFICATION_WEBHOOK_URL unset. The scan will run normally, no notifications will be sent.

Next​

Severity Rules - understand and tune which changes trigger alerts.

To change payload format or add a new webhook channel, see Customize: Notifications.