Rewritten to match the style of other docs pages

RogerSelwyn · RogerSelwyn · commit bbdcc9c18561 · 2025-12-31T12:25:33.000Z
diff --git a/docs/source/usage/subscriptions.rst b/docs/source/usage/subscriptions.rst
@@ -1,89 +1,33 @@
 Subscriptions
 =============
 
-Subscriptions provides the ability to create and manage webhook subscriptions against Microsoft Graph. Read here for more details on MS Graph subscriptions
+Subscriptions provides the ability to create and manage webhook subscriptions for change notifications against Microsoft Graph. Read here for more details on MS Graph subscriptions
 
 - https://learn.microsoft.com/en-us/graph/api/resources/subscription?view=graph-rest-1.0
 - https://learn.microsoft.com/en-us/graph/change-notifications-delivery-webhooks?tabs=http
 
+Create a Subscription
+^^^^^^^^^^^^^^^^^^^^^
 
-**Example on how to use and setup webhooks**
-
-Quickstart for this example:
-
-#. Run Flask locally with the following command:
-
-    - ``flask --app examples/subscriptions_example.py run --debug``
-
-#. Expose HTTPS via a tunnel to your localhost:5000:
-
-    - Free: `pinggy <https://pinggy.io/>`_ to get ``https://<subdomain>.pinggy.link`` -> http://localhost:5000
-    - Paid/free-tier: `ngrok <https://ngrok.com/>`_: ngrok http 5000, note the https URL.
-    
-#. Use the tunnel HTTPS URL as notification_url pointing to /webhook, URL-encoded. 
-#. To create a subscription, follow the example request below:
-
-    - ``https://<your-tunnel-host>/subscriptions?notification_url=https%3A%2F%2F<your-tunnel-host>%2Fwebhook&client_state=abc123``
-
-#. To list subscriptions, follow the example request below:
-
-    - ``http://<your-tunnel-host>/subscriptions/list``
-
-#. To renew a subscription, follow the example request below: 
-
-    - ``http://<your-tunnel-host>/subscriptions/<subscription_id>/renew?expiration_minutes=55``
-
-#. To delete a subscription, follow the example request below:
-
-    - ``http://<your-tunnel-host>/subscriptions/<subscription_id>/delete``
-
-Graph will call ``https://<your-tunnel-host>/webhook``; this app echoes validationToken and returns 202 for notifications.
+Assuming a web host (example uses `flask`) and an authenticated account, create a subscription to be notified about new emails.
 
 .. code-block:: python
 
     from flask import Flask, abort, jsonify, request
-    from O365 import Account
-
-    CLIENT_ID = "YOUR CLIENT ID"
-    CLIENT_SECRET = "YOUR CLIENT SECRET"
-    credentials = (CLIENT_ID, CLIENT_SECRET)
-
-    account = Account(credentials)
-    # Pick the scopes that are relevant to you here
-    account.authenticate(
-                scopes=[
-                    "https://graph.microsoft.com/Mail.ReadWrite",
-                    "https://graph.microsoft.com/Mail.Send",
-                    "https://graph.microsoft.com/Calendars.ReadWrite",
-                    "https://graph.microsoft.com/MailboxSettings.ReadWrite",
-                    "https://graph.microsoft.com/User.Read",
-                    "https://graph.microsoft.com/User.ReadBasic.All",
-                    'offline_access'
-                ])
 
     RESOURCE = "/me/mailFolders('inbox')/messages"
-    DEFAULT_EXPIRATION_MINUTES = 10069 # Maximum expiration is 10,070 in the future.
+    DEFAULT_EXPIRATION_MINUTES = 10069  # Maximum expiration is 10,070 in the future for Outlook message.
 
     app = Flask(__name__)
 
-
-    def _int_arg(name: str, default: int) -> int:
-        raw = request.args.get(name)
-        if raw is None:
-            return default
-        try:
-            return int(raw)
-        except ValueError:
-            abort(400, description=f"{name} must be an integer")
-
-
     @app.get("/subscriptions")
     def create_subscription():
+        """Create a subscription."""
         notification_url = request.args.get("notification_url")
         if not notification_url:
             abort(400, description="notification_url is required")
 
-        expiration_minutes = _int_arg("expiration_minutes", DEFAULT_EXPIRATION_MINUTES)
+        expiration_minutes = int(request.args.get("expiration_minutes", DEFAULT_EXPIRATION_MINUTES))
         client_state = request.args.get("client_state")
         resource = request.args.get("resource", RESOURCE)
 
@@ -96,59 +40,179 @@ Graph will call ``https://<your-tunnel-host>/webhook``; this app echoes validati
         )
         return jsonify(subscription), 201
 
+    @app.post("/webhook")
+    def webhook_handler():
+        """Handle Microsoft Graph webhook calls.
+
+        - During subscription validation, Graph sends POST with ?validationToken=... .
+        We must echo the token as plain text within 10 seconds.
+        - For change notifications, Graph posts JSON; we just log/ack.
+        """
+        validation_token = request.args.get("validationToken")
+        if validation_token:
+            # Echo back token exactly as plain text with HTTP 200.
+            return validation_token, 200, {"Content-Type": "text/plain"}
+
+        # Change notifications: inspect or log as needed.
+        payload = request.get_json(silent=True) or {}
+        print("Received notification payload:", payload)
+        return ("", 202)
+
+Use this url:
+
+    ``https://<your-tunnel-host>/subscriptions?notification_url=https%3A%2F%2F<your-tunnel-host>%2Fwebhook&client_state=abc123``
+
+HTTP status 201 and the following should be returned:
+
+.. code-block:: JSON
+
+    {
+        "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
+        "applicationId": "12345678-bad9-4c34-94d6-f9a1388522f8",
+        "changeType": "created",
+        "clientState": "abc123",
+        "creatorId": "12345678-a5c7-46da-8107-b25090a1ed66",
+        "encryptionCertificate": null,
+        "encryptionCertificateId": null,
+        "expirationDateTime": "2026-01-07T11:20:42.305776Z",
+        "id": "548355f8-c2c0-47ae-aac7-3ad02b2dfdb1",
+        "includeResourceData": null,
+        "latestSupportedTlsVersion": "v1_2",
+        "lifecycleNotificationUrl": null,
+        "notificationQueryOptions": null,
+        "notificationUrl": "https://<your-tunnel-host>/webhook",
+        "notificationUrlAppId": null,
+        "resource": "/me/mailFolders('inbox')/messages"
+    }
+
+List Subscriptions
+^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
 
     @app.get("/subscriptions/list")
     def list_subscriptions():
-        limit_raw = request.args.get("limit")
-        limit = None
-        if limit_raw is not None:
-            try:
-                limit = int(limit_raw)
-            except ValueError:
-                abort(400, description="limit must be an integer")
-            if limit <= 0:
-                abort(400, description="limit must be a positive integer")
-
+        """List all subscriptions."""
+        limit = int(request.args.get("limit"))
         subscriptions = account.subscriptions().list_subscriptions(limit=limit)
         return jsonify(list(subscriptions)), 200
 
+Use this url:
+
+    ``https://<your-tunnel-host>/subscriptions/list``
+
+HTTP status 200 and the following should be returned:
+
+.. code-block:: JSON
+
+    [
+        {
+            "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
+            "applicationId": "12345678-bad9-4c34-94d6-f9a1388522f8",
+            "changeType": "created",
+            "clientState": "abc123",
+            "creatorId": "12345678-a5c7-46da-8107-b25090a1ed66",
+            "encryptionCertificate": null,
+            "encryptionCertificateId": null,
+            "expirationDateTime": "2026-01-07T11:20:42.305776Z",
+            "id": "548355f8-c2c0-47ae-aac7-3ad02b2dfdb1",
+            "includeResourceData": null,
+            "latestSupportedTlsVersion": "v1_2",
+            "lifecycleNotificationUrl": null,
+            "notificationQueryOptions": null,
+            "notificationUrl": "https://<your-tunnel-host>/webhook",
+            "notificationUrlAppId": null,
+            "resource": "/me/mailFolders('inbox')/messages"
+        }
+    ]
+
+Renew a Subscription
+^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
 
     @app.get("/subscriptions/<subscription_id>/renew")
     def renew_subscription(subscription_id: str):
-        expiration_minutes = _int_arg("expiration_minutes", DEFAULT_EXPIRATION_MINUTES)
+        """Renew a subscription."""
+        expiration_minutes = int(request.args.get("expiration_minutes", DEFAULT_EXPIRATION_MINUTES))
         updated = account.subscriptions().renew_subscription(
             subscription_id,
             expiration_minutes=expiration_minutes,
         )
         return jsonify(updated), 200
 
+Use this url:
+
+    ``http://<your-tunnel-host>/subscriptions/548355f8-c2c0-47ae-aac7-3ad02b2dfdb1/renew?expiration_minutes=10069``
+
+HTTP status 200 and the following should be returned:
+
+.. code-block:: JSON
+
+    {
+        "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#subscriptions/$entity",
+        "applicationId": "12345678-bad9-4c34-94d6-f9a1388522f8",
+        "changeType": "created",
+        "clientState": "abc123",
+        "creatorId": "12345678-a5c7-46da-8107-b25090a1ed66",
+        "encryptionCertificate": null,
+        "encryptionCertificateId": null,
+        "expirationDateTime": "2026-01-07T11:35:40.301594Z",
+        "id": "548355f8-c2c0-47ae-aac7-3ad02b2dfdb1",
+        "includeResourceData": null,
+        "latestSupportedTlsVersion": "v1_2",
+        "lifecycleNotificationUrl": null,
+        "notificationQueryOptions": null,
+        "notificationUrl": "https://<your-tunnel-host>/webhook",
+        "notificationUrlAppId": null,
+        "resource": "/me/mailFolders('inbox')/messages"
+    }
+
+Delete a Subscription
+^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: python
 
     @app.get("/subscriptions/<subscription_id>/delete")
     def delete_subscription(subscription_id: str):
+        """Delete a subscription."""
         deleted = account.subscriptions().delete_subscription(subscription_id)
         if not deleted:
             abort(404, description="Subscription not found")
         return ("", 204)
 
+Use this url:
 
-    @app.post("/webhook")
-    def webhook_handler():
-        """Handle Microsoft Graph webhook calls.
+    ``http://<your-tunnel-host>/subscriptions/548355f8-c2c0-47ae-aac7-3ad02b2dfdb1/delete``
 
-        - During subscription validation, Graph sends POST with ?validationToken=... .
-        We must echo the token as plain text within 10 seconds.
-        - For change notifications, Graph posts JSON; we just log/ack.
-        """
-        validation_token = request.args.get("validationToken")
-        if validation_token:
-            # Echo back token exactly as plain text with HTTP 200.
-            return validation_token, 200, {"Content-Type": "text/plain"}
+HTTP status 204 should be returned.
 
-        # Change notifications: inspect or log as needed.
-        payload = request.get_json(silent=True) or {}
-        print("Received notification payload:", payload)
-        return ("", 202)
+Webhook
+^^^^^^^
 
+With a subscription as described above and an email sent to the inbox, a webhook will be received as below:
+
+.. code-block:: python
 
-    if __name__ == "__main__":
-        app.run(debug=True, ssl_context=("examples/cert.pem", "examples/key.pem"))
+    {
+        'value': [
+            {
+                'subscriptionId': '548355f8-c2c0-47ae-aac7-3ad02b2dfdb12', 
+                'subscriptionExpirationDateTime': '2026-01-07T11:35:40.301594+00:00', 
+                'changeType': 'created', 
+                'resource': 'Users/12345678-a5c7-46da-8107-b25090a1ed66/Messages/<long_guid>=', 
+                'resourceData': {
+                    '@odata.type': '#Microsoft.Graph.Message', 
+                    '@odata.id': 'Users/12345678-a5c7-46da-8107-b25090a1ed66/Messages/<long_guid>=', 
+                    '@odata.etag': 'W/"CQAAABYACCCoiRErLbiNRJDCFyMjq4khBBnH4N7A"', 
+                    'id': '<long_guid>='
+                }, 
+                'clientState': 'abc123', 
+                'tenantId': '12345678-abcd-1234-abcd-1234567890ab'
+            }
+        ]
+    }
+
+The client state should be validated for accuracy and if correct, the message can be acted upon as approriate for the type of subscription.
+
+An example application can be found in the examples directory here - https://github.com/O365/python-o365/blob/master/examples/subscriptions_example.py
diff --git a/pyproject.toml b/pyproject.toml
@@ -35,6 +35,7 @@ dev = [
     "pytest>=8.3.4",
     "sphinx>=7.4.7",
     "sphinx-rtd-theme>=3.0.2",
+    "flask"
 ]
 
 [build-system]

Original file line number	Diff line number	Diff line change
`@@ -35,6 +35,7 @@ dev = [`
`35`	`35`	`"pytest>=8.3.4",`
`36`	`36`	`"sphinx>=7.4.7",`
`37`	`37`	`"sphinx-rtd-theme>=3.0.2",`
	`38`	`+ "flask"`
`38`	`39`	`]`
`39`	`40`
`40`	`41`	`[build-system]`