Create Microsoft Graph webhook subscriptions for a Node.js app, so that it can receive notifications of changes in a user’s Microsoft account data.
page_type: sample products:
Subscribe for Microsoft Graph change notifications to be notified when your user's data changes, so you don't have to poll for changes.
This sample NodeJS web application shows how to subscribe for change notifications as well as how to validate and decrypt change notifications with resource data when supported by the resource.
User-delegated authentication represents a user and the application being used when calling the Microsoft Graph. This type of authentication is best suited for scenarios when the user interacts with the application. Application only authentication represents only the application itself when calling the Microsoft Graph, without any notion of user. This type of authentication is best suited for background services, daemons or other kind of applications users are not directly interacting with.
See the list of permissions and authentication types permitted for each supported resource in Microsoft Graph.
The following are common tasks that an application performs with webhooks subscriptions:
To use the Webhook sample, you need the following:
You can install OpenSSL on windows using chocolatey with
choco install openssl -y
(run as administrator).
Select Azure Active Directory in the left-hand navigation, then select App registrations under Manage.
Select New registration. On the Register an application page, set the values as follows.
Node.js Graph Notification Webhook Sample
.Web
and set the value to http://localhost:3000/delegated/callback
.Select Register to create the app. On the app's Overview page, copy the value of the Application (client) ID and Directory (tenant) ID and save them for later.
Select Certificates & secrets under Manage. Select the New client secret button. Enter a value in Description and select one of the options for Expires and select Add.
Copy the Value of the new secret before you leave this page. It will never be displayed again. Save the value for later.
Select API permissions under Manage.
In the list of pages for the app, select API permissions, then select Add a permission.
Make sure that the Microsoft APIs tab is selected, then select Microsoft Graph.
Select Application permissions, then find and enable the ChannelMessage.Read.All permission. Select Add permissions to add the enabled permission.
Note: To create subscriptions for other resources you need to select different permissions as documented here
In the Configured permissions list, select the ellipses (...
) in the User.Read row, and select Remove permission. The User.Read permission will be requested dynamically as part of the user sign-in process.
Select Grant admin consent for name of your organization
and Yes. This grants consent to the permissions of the application registration you just created to the current organization.
You must expose a public HTTPS endpoint to create a subscription and receive notifications from Microsoft Graph. While testing, you can use ngrok to temporarily allow messages from Microsoft Graph to tunnel to a localhost port on your computer.
You can use the ngrok web interface http://127.0.0.1:4040
to inspect the HTTP traffic that passes through the tunnel. To download and learn more about using ngrok, see the ngrok website.
Run the following command in your command-line interface (CLI) to start an ngrok session.
ngrok http 3000
Copy the HTTPS URL that's shown in the console. You'll use this to configure your notification URL in the sample.
IMPORTANT: Keep the console open while testing. If you close it, the tunnel also closes and you'll need to generate a new URL and update the sample. See troubleshooting for more information about using tunnels.
Rename sample.env to .env and open it in a text editor.
Replace YOUR_CLIENT_ID_HERE
with the client ID of your registered Azure application.
Replace YOUR_CLIENT_SECRET_HERE
with the client secret of your registered Azure application.
Replace YOUR_TENANT_ID_HERE
with the tenant ID of your organization. This information can be found next to the client ID on the application management page, note: if you choose Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox) replace this value for "common".
Replace YOUR_NGROK_URL_HERE
with the HTTPS ngrok URL you copied earlier.
(Optional) - You can update the CERTIFICATE_PATH
, CERTIFICATE_ID
, PRIVATE_KEY_PATH
, and PRIVATE_KEY_PASSWORD
if desired.
(Optional) - If you are running the sample on Windows, you can provide a path to openssl.exe in the WINDOWS_OPENSSL_PATH
value in .env.
Install the dependencies running the following command:
npm install
Start the application with the following command:
npm start
Note: You can also attach the debugger included in Microsoft Visual Studio Code using the included launch.json. For more information, see Node.js debugging in VS Code.
Open a browser and go to http://localhost:3000.
Choose the Sign in and subscribe button and sign in with a work or school account.
Review and consent to the requested permissions. The subscription is created and you are redirected to a page displaying any notification being received.
Send an email to yourself. A notification appears showing the subject and message ID.
If you previously subscribed to a user's inbox, choose the Delete subscription button to return to the home page.
Choose the Subscribe button. The subscription is created and you are redirected to a page displaying any notification being received.
Post a message to a channel in any team in Microsoft Teams. A notification appears showing the sender's name and the message.
See the dedicated troubleshooting page.
If you'd like to contribute to this sample, see CONTRIBUTING.MD.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.
We'd love to get your feedback about the Microsoft Graph Webhook sample. You can send your questions and suggestions to us in the Issues section of this repository.
Questions about Microsoft Graph in general should be posted to Microsoft Q&A. Make sure that your questions or comments are tagged with the relevant Microsoft Graph tag.