Microsoft Graph Webhook - COMPASS API Documentation

Microsoft Graph webhook for new email notifications

curl --request POST \
  --url http://localhost:2000/email-meter/reservation-hook \
  --header 'Content-Type: application/json' \
  --data '
{
  "value": [
    {
      "subscriptionId": "a12b34cd-56e7-890f-12gh-3456ijkl7890",
      "changeType": "created",
      "resource": "me/messages/AAMkADNkZDIxY2E1L...",
      "resourceData": {
        "id": "AAMkADNkZDIxY2E1LTQzNDUtNGUwYS04ZTFlLTY1NjVhYjMxZTc2MwBGAAAAA..."
      }
    }
  ]
}
'

import requests

url = "http://localhost:2000/email-meter/reservation-hook"

payload = { "value": [
        {
            "subscriptionId": "a12b34cd-56e7-890f-12gh-3456ijkl7890",
            "changeType": "created",
            "resource": "me/messages/AAMkADNkZDIxY2E1L...",
            "resourceData": { "id": "AAMkADNkZDIxY2E1LTQzNDUtNGUwYS04ZTFlLTY1NjVhYjMxZTc2MwBGAAAAA..." }
        }
    ] }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    value: [
      {
        subscriptionId: 'a12b34cd-56e7-890f-12gh-3456ijkl7890',
        changeType: 'created',
        resource: 'me/messages/AAMkADNkZDIxY2E1L...',
        resourceData: {id: 'AAMkADNkZDIxY2E1LTQzNDUtNGUwYS04ZTFlLTY1NjVhYjMxZTc2MwBGAAAAA...'}
      }
    ]
  })
};

fetch('http://localhost:2000/email-meter/reservation-hook', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "2000",
  CURLOPT_URL => "http://localhost:2000/email-meter/reservation-hook",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'value' => [
        [
                'subscriptionId' => 'a12b34cd-56e7-890f-12gh-3456ijkl7890',
                'changeType' => 'created',
                'resource' => 'me/messages/AAMkADNkZDIxY2E1L...',
                'resourceData' => [
                                'id' => 'AAMkADNkZDIxY2E1LTQzNDUtNGUwYS04ZTFlLTY1NjVhYjMxZTc2MwBGAAAAA...'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:2000/email-meter/reservation-hook"

	payload := strings.NewReader("{\n  \"value\": [\n    {\n      \"subscriptionId\": \"a12b34cd-56e7-890f-12gh-3456ijkl7890\",\n      \"changeType\": \"created\",\n      \"resource\": \"me/messages/AAMkADNkZDIxY2E1L...\",\n      \"resourceData\": {\n        \"id\": \"AAMkADNkZDIxY2E1LTQzNDUtNGUwYS04ZTFlLTY1NjVhYjMxZTc2MwBGAAAAA...\"\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:2000/email-meter/reservation-hook")
  .header("Content-Type", "application/json")
  .body("{\n  \"value\": [\n    {\n      \"subscriptionId\": \"a12b34cd-56e7-890f-12gh-3456ijkl7890\",\n      \"changeType\": \"created\",\n      \"resource\": \"me/messages/AAMkADNkZDIxY2E1L...\",\n      \"resourceData\": {\n        \"id\": \"AAMkADNkZDIxY2E1LTQzNDUtNGUwYS04ZTFlLTY1NjVhYjMxZTc2MwBGAAAAA...\"\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:2000/email-meter/reservation-hook")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"value\": [\n    {\n      \"subscriptionId\": \"a12b34cd-56e7-890f-12gh-3456ijkl7890\",\n      \"changeType\": \"created\",\n      \"resource\": \"me/messages/AAMkADNkZDIxY2E1L...\",\n      \"resourceData\": {\n        \"id\": \"AAMkADNkZDIxY2E1LTQzNDUtNGUwYS04ZTFlLTY1NjVhYjMxZTc2MwBGAAAAA...\"\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

"ValidationTokenExample123456"

POST

email-meter

reservation-hook

Microsoft Graph webhook for new email notifications

curl --request POST \
  --url http://localhost:2000/email-meter/reservation-hook \
  --header 'Content-Type: application/json' \
  --data '
{
  "value": [
    {
      "subscriptionId": "a12b34cd-56e7-890f-12gh-3456ijkl7890",
      "changeType": "created",
      "resource": "me/messages/AAMkADNkZDIxY2E1L...",
      "resourceData": {
        "id": "AAMkADNkZDIxY2E1LTQzNDUtNGUwYS04ZTFlLTY1NjVhYjMxZTc2MwBGAAAAA..."
      }
    }
  ]
}
'

import requests

url = "http://localhost:2000/email-meter/reservation-hook"

payload = { "value": [
        {
            "subscriptionId": "a12b34cd-56e7-890f-12gh-3456ijkl7890",
            "changeType": "created",
            "resource": "me/messages/AAMkADNkZDIxY2E1L...",
            "resourceData": { "id": "AAMkADNkZDIxY2E1LTQzNDUtNGUwYS04ZTFlLTY1NjVhYjMxZTc2MwBGAAAAA..." }
        }
    ] }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    value: [
      {
        subscriptionId: 'a12b34cd-56e7-890f-12gh-3456ijkl7890',
        changeType: 'created',
        resource: 'me/messages/AAMkADNkZDIxY2E1L...',
        resourceData: {id: 'AAMkADNkZDIxY2E1LTQzNDUtNGUwYS04ZTFlLTY1NjVhYjMxZTc2MwBGAAAAA...'}
      }
    ]
  })
};

fetch('http://localhost:2000/email-meter/reservation-hook', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "2000",
  CURLOPT_URL => "http://localhost:2000/email-meter/reservation-hook",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'value' => [
        [
                'subscriptionId' => 'a12b34cd-56e7-890f-12gh-3456ijkl7890',
                'changeType' => 'created',
                'resource' => 'me/messages/AAMkADNkZDIxY2E1L...',
                'resourceData' => [
                                'id' => 'AAMkADNkZDIxY2E1LTQzNDUtNGUwYS04ZTFlLTY1NjVhYjMxZTc2MwBGAAAAA...'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:2000/email-meter/reservation-hook"

	payload := strings.NewReader("{\n  \"value\": [\n    {\n      \"subscriptionId\": \"a12b34cd-56e7-890f-12gh-3456ijkl7890\",\n      \"changeType\": \"created\",\n      \"resource\": \"me/messages/AAMkADNkZDIxY2E1L...\",\n      \"resourceData\": {\n        \"id\": \"AAMkADNkZDIxY2E1LTQzNDUtNGUwYS04ZTFlLTY1NjVhYjMxZTc2MwBGAAAAA...\"\n      }\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:2000/email-meter/reservation-hook")
  .header("Content-Type", "application/json")
  .body("{\n  \"value\": [\n    {\n      \"subscriptionId\": \"a12b34cd-56e7-890f-12gh-3456ijkl7890\",\n      \"changeType\": \"created\",\n      \"resource\": \"me/messages/AAMkADNkZDIxY2E1L...\",\n      \"resourceData\": {\n        \"id\": \"AAMkADNkZDIxY2E1LTQzNDUtNGUwYS04ZTFlLTY1NjVhYjMxZTc2MwBGAAAAA...\"\n      }\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:2000/email-meter/reservation-hook")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"value\": [\n    {\n      \"subscriptionId\": \"a12b34cd-56e7-890f-12gh-3456ijkl7890\",\n      \"changeType\": \"created\",\n      \"resource\": \"me/messages/AAMkADNkZDIxY2E1L...\",\n      \"resourceData\": {\n        \"id\": \"AAMkADNkZDIxY2E1LTQzNDUtNGUwYS04ZTFlLTY1NjVhYjMxZTc2MwBGAAAAA...\"\n      }\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

"ValidationTokenExample123456"

Webhook endpoint used by Microsoft Graph for email notification events. This endpoint does not require authentication since it’s called by Microsoft servers.

Request

Query Parameters

Parameter	Type	Required	Description
validationToken	string	No	Validation token sent by Microsoft Graph during webhook registration

Request Body (for email notifications)

{
  "value": [
    {
      "subscriptionId": "a12b34cd-56e7-890f-12gh-3456ijkl7890",
      "changeType": "created",
      "resource": "me/messages/AAMkADNkZDIxY2E1L...",
      "resourceData": {
        "id": "AAMkADNkZDIxY2E1LTQzNDUtNGUwYS04ZTFlLTY1NjVhYjMxZTc2MwBGAAAAA..."
      }
    }
  ]
}

Request Body Schema

Field	Type	Required	Description
value	array	No	Array of Microsoft Graph notification objects
subscriptionId	string	No	Unique subscription identifier
changeType	string	No	Type of change (created, updated, deleted)
resource	string	No	Resource identifier
resourceData	object	No	Data about the changed resource

Response

200 OK - Webhook validation (returns validation token)

ValidationTokenExample123456

200 OK - Email notification processed

{
  "status": "processed",
  "message": "Email notification received and queued for processing"
}

400 Bad Request

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid or malformed request"
  }
}

500 Internal Server Error

{
  "error": {
    "code": "SERVER_ERROR",
    "message": "Internal server error"
  }
}

Examples

Webhook Validation (during setup)

# Microsoft Graph calls this with validationToken
curl -X POST 'http://localhost:2000/email-meter/reservation-hook?validationToken=ValidationTokenExample123456'

Email Notification (real-time)

# Microsoft Graph calls this when new email arrives
curl -X POST 'http://localhost:2000/email-meter/reservation-hook' \
  -H 'Content-Type: application/json' \
  -d '{
    "value": [
      {
        "subscriptionId": "a12b34cd-56e7-890f-12gh-3456ijkl7890",
        "changeType": "created",
        "resource": "me/messages/AAMkADNkZDIxY2E1L...",
        "resourceData": {
          "id": "AAMkADNkZDIxY2E1LTQzNDUtNGUwYS04ZTFlLTY1NjVhYjMxZTc2MwBGAAAAA..."
        }
      }
    ]
  }'

Notes

No Authentication Required: This endpoint is called by Microsoft servers
Two Modes: Validation during setup, notifications during operation
Validation Token: Must be echoed back exactly as received during setup
Real-time Processing: Email notifications are processed immediately
Queue System: Notifications are queued for asynchronous processing

Webhook Lifecycle

1. Setup Phase

Microsoft Graph sends validation token
Endpoint returns the token unchanged
Subscription becomes active

2. Operation Phase

Microsoft Graph sends email event notifications
Endpoint processes and acknowledges notifications
Emails are analyzed and statistics updated

Event Types

Change Type	Description	Action Taken
created	New email received	Analyze email, update stats
updated	Email modified	Re-analyze if needed
deleted	Email deleted	Update statistics accordingly

Processing Flow

Receive Notification: Microsoft Graph sends webhook
Validate Request: Verify source and format
Queue for Processing: Add to analysis queue
Email Analysis: Extract metadata and content
Update Statistics: Refresh all relevant metrics
Trigger Notifications: Send alerts if configured

Security Considerations

Source Verification: Verify requests come from Microsoft Graph
Rate Limiting: Handle high volume of notifications
Data Privacy: Process email content securely
Error Handling: Graceful degradation on processing failures

Troubleshooting

Common Issues

Validation Fails: Ensure exact token is returned
Missing Notifications: Check subscription status
Processing Delays: Monitor queue health
Duplicate Events: Implement deduplication logic

Monitoring

Track webhook response times
Monitor notification processing queue
Alert on failed validation attempts
Log all webhook events for auditing

Configuration

The webhook endpoint URL must be:

Publicly accessible: Microsoft servers must reach it
HTTPS enabled: Required for security
Responsive: Must respond within timeout limits
Reliable: Handle Microsoft’s retry logic

Best Practices

Fast Response: Respond quickly to webhook calls
Async Processing: Use background jobs for email analysis
Error Recovery: Implement retry logic for failures
Logging: Log all webhook events for debugging
Monitoring: Set up alerts for webhook health

Query Parameters

validationToken

string

Validation token sent by Microsoft Graph during webhook registration. The API must return this token as plain text to validate the subscription.

Body

application/json

value

object[]

Array of Microsoft Graph notification objects.

Show child attributes

Response

Successfully processed the webhook event or returned validation token

The response is of type string.

Example:

"ValidationTokenExample123456"

Email Count Statistics

​Request

​Query Parameters

​Request Body (for email notifications)

​Request Body Schema

​Response

​200 OK - Webhook validation (returns validation token)

​200 OK - Email notification processed

​400 Bad Request

​500 Internal Server Error

​Examples

​Webhook Validation (during setup)

​Email Notification (real-time)

​Notes

​Webhook Lifecycle

​1. Setup Phase

​2. Operation Phase

​Event Types

​Processing Flow

​Security Considerations

​Troubleshooting

​Common Issues

​Monitoring

​Configuration

​Best Practices

Query Parameters

Body

Response

Request

Query Parameters

Request Body (for email notifications)

Request Body Schema

Response

200 OK - Webhook validation (returns validation token)

200 OK - Email notification processed

400 Bad Request

500 Internal Server Error

Examples

Webhook Validation (during setup)

Email Notification (real-time)

Notes

Webhook Lifecycle

1. Setup Phase

2. Operation Phase

Event Types

Processing Flow

Security Considerations

Troubleshooting

Common Issues

Monitoring

Configuration

Best Practices