Webhooks

Handle Outlook (Microsoft Graph) change notification

POST
/api/webhook/email/outlook

Inbound webhook called by Microsoft Graph when a subscribed mailbox receives a new message. On subscription creation Graph performs a validation handshake by sending a validationToken query parameter, which the endpoint echoes back as plain text. Notification payloads are accepted with 202 and processed asynchronously.

Query Parameters

validationToken?string

Sent by Microsoft Graph during subscription validation. When present the endpoint echoes it back as text/plain and skips notification processing.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Microsoft Graph change notification batch.

Response Body

text/plain

text/plain

application/json

curl -X POST "https://example.com/api/webhook/email/outlook" \  -H "Content-Type: application/json" \  -d '{    "value": [      {        "subscriptionId": "7f4b2c1d-9e0a-4b3c-8d5e-6f7a8b9c0d1e",        "subscriptionExpirationDateTime": "2026-05-20T15:04:01.135Z",        "changeType": "created",        "resource": "Users/ops@acme.example/Messages/AAMkAGI2T..==",        "resourceData": {          "@odata.type": "#Microsoft.Graph.Message",          "@odata.id": "Users/ops@acme.example/Messages/AAMkAGI2T..==",          "id": "AAMkAGI2T..=="        },        "clientState": "tether-outlook-secret",        "tenantId": "5f7b1c2e-8a1d-4e00-12c3-b4a55f7b1c2e"      }    ]  }'
"A1B2C3D4-E5F6-7890-ABCD-EF1234567890"