Setting Up an Online SharePoint Site with App Registration for Webhook and Integration with InspectRAG
Table of Contents
- Introduction
- Prerequisites
- Setting Up an Online SharePoint Site
- Creating an App Registration in Azure Active Directory
- Register the App
- Extracting Client ID and Tenant ID
- Creating a Client Secret
- Configuring API Permissions
- Obtaining SharePoint Hostname and Site Path
- Setting Up Webhooks for File Download and Change Notifications
- Authenticating with Microsoft Graph API
- Registering a Webhook
- Downloading Files and Checking for File Changes
- Conclusion
- References
Introduction
This guide provides a comprehensive walkthrough for setting up an online SharePoint site and registering an application in Azure Active Directory (Azure AD). It also covers how to extract essential identifiers, configure API permissions, and set up webhooks to download files and monitor file changes using Microsoft Graph API.
Prerequisites
- An Office 365 tenant with SharePoint Online.
- Administrative access to Azure Active Directory.
- Basic knowledge of SharePoint Online and Azure concepts.
Setting Up an Online SharePoint Site
-
Sign in to Office 365:
-
Go to Office 365 Portal.
-
Log in with your administrator credentials.
-
Access the SharePoint Admin Center:
-
Click on the App Launcher (waffle icon) in the top-left corner.
- Select Admin.
-
In the left-hand menu, expand Admin centers and click on SharePoint.
-
Create a New Site:
-
In the SharePoint admin center, click on Active sites.
-
Click on Create and choose either Team site or Communication site.
-
Configure Site Details:
-
Site name: Enter a unique name for your site.
- Site address: This will be part of your site's URL.
- Primary administrator: Assign a site owner.
-
Time zone: Select the appropriate time zone for your location.
-
Finalize Site Creation:
-
Click Finish to create the site.
- Wait for the site to be provisioned (this may take a few minutes).
Creating an App Registration in Azure Active Directory
Register the App
-
Access Azure Portal:
-
Navigate to the Azure Portal.
-
Log in with your administrator credentials.
-
Navigate to Azure Active Directory:
-
In the left-hand menu, select Azure Active Directory.
-
Go to App Registrations:
-
Click on App registrations in the Azure AD menu.
-
Click on New registration.
-
Register Your Application:
-
Name: Enter a meaningful name for your app (e.g., "SharePointWebhookApp").
- Supported account types: Select Accounts in this organizational directory only.
- Redirect URI: Leave blank for now unless you have a specific redirect URI.
- Click Register.
Extracting Client ID and Tenant ID
-
Application (client) ID:
-
After registration, you will be on the app's Overview page.
-
Copy the Application (client) ID. This is your Client ID.
-
Directory (tenant) ID:
-
From the same Overview page, copy the Directory (tenant) ID. This is your Tenant ID.
Creating a Client Secret
-
Navigate to Certificates & Secrets:
-
In the left-hand menu of your app, click on Certificates & secrets.
-
Create a New Client Secret:
-
Click on New client secret.
- Description: Provide a description (e.g., "AppSecretKey").
- Expires: Choose the expiration period (e.g., 6 months, 12 months).
-
Click Add.
-
Copy the Client Secret:
-
After creation, copy the Value of the client secret. This is your Secret Key.
- Important: This value is only displayed once. Store it securely.
Configuring API Permissions
-
Navigate to API Permissions:
-
In your app's left-hand menu, click on API permissions.
-
Add Permissions:
-
Click on Add a permission.
-
Under Microsoft APIs, select Microsoft Graph.
-
Select Permission Type:
-
Choose Application permissions since webhooks generally run without user interaction.
-
Add the Required Permissions:
-
For Webhooks and File Access:
Sites.Read.All
Sites.Manage.All
(required for managing webhooks)Files.Read.All
-
Select each permission by expanding the categories and checking the boxes.
-
Grant Admin Consent:
-
After adding the permissions, click on Grant admin consent for [Your Organization].
- Confirm by clicking Yes.
Obtaining SharePoint Hostname and Site Path
-
SharePoint Hostname:
-
Navigate to your SharePoint site.
- The URL will be in the format:
https://[your-tenant-name].sharepoint.com
. -
[your-tenant-name].sharepoint.com
is your SharePoint Hostname. -
SharePoint Site Path:
-
From your site's URL, extract the site path.
- Example URL:
https://your-tenant-name.sharepoint.com/sites/YourSiteName
. - The site path is
/sites/YourSiteName
.
Setting Up Webhooks for File Download and Change Notifications
Authenticating with Microsoft Graph API
-
Obtain an Access Token:
-
Use the OAuth 2.0 client credentials flow.
-
Token Endpoint:
-
Parameters:
grant_type
:client_credentials
client_id
: Your Client IDclient_secret
: Your Secret Keyscope
:https://graph.microsoft.com/.default
-
Example Request using cURL:
curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d 'grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_SECRET_KEY&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default' \
https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token
-
Store the Access Token:
-
The response will contain an
access_token
. - Use this token in the
Authorization
header for subsequent API calls.
Registering a Webhook
-
Get the Site ID:
-
Endpoint:
-
Example:
-
Include the
Authorization
header with your access token. -
Extract the Site ID:
-
The response will contain the
id
of the site. -
Create a Subscription:
-
Endpoint:
-
Request Body:
-
Replace
{site-id}
with the actual site ID. -
The
notificationUrl
is your endpoint to receive notifications. -
Example Request using cURL:
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-d '{
"changeType": "updated",
"notificationUrl": "https://yourdomain.com/notifications",
"resource": "/sites/YOUR_SITE_ID/drive/root",
"expirationDateTime": "2025-12-31T23:59:59Z",
"clientState": "yourSecretClientState"
}' \
https://graph.microsoft.com/v1.0/subscriptions
-
Handle Validation Tokens:
-
Microsoft Graph will send a validation request to your
notificationUrl
. - Your endpoint must respond with the validation token within 5 seconds.
Downloading Files and Checking for File Changes
-
Download a File:
-
Endpoint:
-
Replace
{item-id}
with the ID of the file. -
The response will be the file content.
-
Check for File Changes using Delta Query:
-
Endpoint:
-
Use the
deltaLink
provided in the response for subsequent requests to get changes since the last query. -
Process Notifications:
-
When a change occurs, Microsoft Graph sends a notification to your
notificationUrl
. - The notification contains information about the change.
- Use this data to make API calls to download or process the changed files.
Conclusion
You have successfully set up an online SharePoint site and registered an app in Azure AD. You have also learned how to extract essential identifiers, configure API permissions, and set up webhooks using Microsoft Graph API to download files and monitor file changes.
References
- Microsoft Graph API Documentation
- Authenticate with the Microsoft Identity Platform
- Set up notifications for changes in user data using Microsoft Graph
- Use the Microsoft Graph API to work with files in SharePoint and OneDrive
Note: Replace placeholders like YOUR_CLIENT_ID
, YOUR_SECRET_KEY
, YOUR_TENANT_ID
, your-tenant-name
, YourSiteName
, and yourdomain.com
with your actual values.