Microsoft Graph Webhooks - Simply Explained

1
00:00:00,000 --> 00:00:04,880
Hello everyone and welcome to another episode of Microsoft Knowledge Nuggets here on M365.

2
00:00:04,880 --> 00:00:06,360
FM, I'm your host, Mirko Peters.

3
00:00:06,360 --> 00:00:10,760
Today's topic is one that almost everyone building with Microsoft 365 has heard of,

4
00:00:10,760 --> 00:00:14,160
but very few people can explain clearly what exactly are graph webhooks.

5
00:00:14,160 --> 00:00:16,960
Why should you care about them instead of doing things the old way?

6
00:00:16,960 --> 00:00:18,760
Imagine you're expecting an important letter.

7
00:00:18,760 --> 00:00:20,480
You walk to your mailbox. It's empty.

8
00:00:20,480 --> 00:00:23,040
You walk back. 10 minutes later, you check again.

9
00:00:23,040 --> 00:00:25,560
Still nothing. You do this all day wasting time and energy.

10
00:00:25,560 --> 00:00:26,520
That's polling.

11
00:00:26,520 --> 00:00:27,840
Now imagine a different world.

12
00:00:27,840 --> 00:00:30,480
The mailman rings your doorbell the moment a letter arrives.

13
00:00:30,480 --> 00:00:33,280
You don't check. You wait for the ring. That's a webhook.

14
00:00:33,280 --> 00:00:36,760
By the end of this episode, you'll understand what graph webhooks are.

15
00:00:36,760 --> 00:00:40,280
Why they replace constant checking and how the pieces fit together.

16
00:00:40,280 --> 00:00:42,800
The polling problem. Let's break this down.

17
00:00:42,800 --> 00:00:46,440
To understand why webhooks matter, you need to understand why polling hurts.

18
00:00:46,440 --> 00:00:48,320
Here's how most applications work today.

19
00:00:48,320 --> 00:00:49,680
Your app needs an answer.

20
00:00:49,680 --> 00:00:52,320
It asks Microsoft Graph, "Hey, any new users?"

21
00:00:52,320 --> 00:00:53,960
Graph responds, "Nope."

22
00:00:53,960 --> 00:00:55,880
So your app waits a bit then asks again.

23
00:00:55,880 --> 00:00:57,240
Any new users now?

24
00:00:57,240 --> 00:01:00,320
Still no. Over and over. This process is polling.

25
00:01:00,320 --> 00:01:03,400
Think of it like constantly calling a friend to ask if they have news.

26
00:01:03,400 --> 00:01:06,400
You dial, they pick up, you check, they say no, you hang up.

27
00:01:06,400 --> 00:01:08,320
Then you call again five minutes later.

28
00:01:08,320 --> 00:01:10,440
And again, you're burning their time and your own.

29
00:01:10,440 --> 00:01:11,560
You're probably annoying them.

30
00:01:11,560 --> 00:01:15,000
Now imagine thousands of apps doing this to Microsoft Graph at the same time.

31
00:01:15,000 --> 00:01:18,400
Every app polling every few minutes, asking the same questions,

32
00:01:18,400 --> 00:01:20,560
getting the same answers. That's a lot of noise.

33
00:01:20,560 --> 00:01:23,440
Microsoft has a name for when you poll too aggressively,

34
00:01:23,440 --> 00:01:26,800
throttling, or as some developers call it, "graph jail."

35
00:01:26,800 --> 00:01:28,880
When you send too many requests, Microsoft says,

36
00:01:28,880 --> 00:01:30,680
"Okay, you're done for a while."

37
00:01:30,680 --> 00:01:32,400
They limit how many calls your app makes,

38
00:01:32,400 --> 00:01:34,240
once your throttleed everything slows down.

39
00:01:34,240 --> 00:01:37,160
The legitimate request pile up, your app stops working properly.

40
00:01:37,160 --> 00:01:38,680
You have no idea when you'll be let out.

41
00:01:38,680 --> 00:01:40,400
How many requests are we talking about?

42
00:01:40,400 --> 00:01:43,240
Say your app pulls every five minutes for user changes.

43
00:01:43,240 --> 00:01:45,440
That works out to 12 requests per hour.

44
00:01:45,440 --> 00:01:47,600
Over a full day, that's 208 requests.

45
00:01:47,600 --> 00:01:48,920
And that's just for one resource.

46
00:01:48,920 --> 00:01:52,440
If you're also polling for groups, files, messages, and calendar events,

47
00:01:52,440 --> 00:01:55,320
you rack up thousands of unnecessary requests per day.

48
00:01:55,320 --> 00:01:56,440
Most of them return nothing.

49
00:01:56,440 --> 00:01:58,440
Zero changes, but you still made the call.

50
00:01:58,440 --> 00:02:01,080
And here's the thing, even if you poll every five minutes,

51
00:02:01,080 --> 00:02:03,640
you're still not getting real-time updates.

52
00:02:03,640 --> 00:02:06,000
A change could happen one minute after your last poll.

53
00:02:06,000 --> 00:02:08,040
You won't know about it for another four minutes.

54
00:02:08,040 --> 00:02:11,000
You're wasting resources and still missing the window.

55
00:02:11,000 --> 00:02:13,040
Now, contrast that with an event-driven approach.

56
00:02:13,040 --> 00:02:15,120
Instead of calling Microsoft Graph every few minutes,

57
00:02:15,120 --> 00:02:16,720
you wait for Microsoft Graph to call you.

58
00:02:16,720 --> 00:02:18,760
You set up a listener, when something changes,

59
00:02:18,760 --> 00:02:20,400
Graph sends you a notification.

60
00:02:20,400 --> 00:02:22,840
You don't dial. You pick up when the phone rings.

61
00:02:22,840 --> 00:02:24,280
What are web hooks?

62
00:02:24,280 --> 00:02:25,920
So what exactly is a web hook?

63
00:02:25,920 --> 00:02:27,400
Here's the simplest definition.

64
00:02:27,400 --> 00:02:31,360
A web hook is an HTTP request sent automatically when something happens.

65
00:02:31,360 --> 00:02:32,600
You don't ask for it.

66
00:02:32,600 --> 00:02:34,560
The server just pushes it to you.

67
00:02:34,560 --> 00:02:35,920
Think of it like a doorbell.

68
00:02:35,920 --> 00:02:38,000
You don't stand outside checking every few minutes.

69
00:02:38,000 --> 00:02:39,120
You install a doorbell.

70
00:02:39,120 --> 00:02:40,840
When someone arrives, they ring it.

71
00:02:40,840 --> 00:02:42,160
You hear the ring and answer.

72
00:02:42,160 --> 00:02:44,280
The doorbell does the watching for you.

73
00:02:44,280 --> 00:02:46,880
Web hooks are sometimes called reverse APIs.

74
00:02:46,880 --> 00:02:50,280
With a normal API, your app makes a request and the server responds.

75
00:02:50,280 --> 00:02:51,520
Your app is in control.

76
00:02:51,520 --> 00:02:53,840
With a web hook, the server sends the request to your app.

77
00:02:53,840 --> 00:02:55,120
The server is in control.

78
00:02:55,120 --> 00:02:57,320
It pushes data instead of waiting for you to ask.

79
00:02:57,320 --> 00:02:59,560
Now Microsoft Graph uses web hooks too,

80
00:02:59,560 --> 00:03:02,240
but Microsoft calls them change notifications.

81
00:03:02,240 --> 00:03:04,080
It's the same thing, just a different name.

82
00:03:04,080 --> 00:03:06,600
When something changes in Microsoft 365,

83
00:03:06,600 --> 00:03:10,240
Graph sends an HTTP post to a URL you provide.

84
00:03:10,240 --> 00:03:12,600
That post contains information about what changed.

85
00:03:12,600 --> 00:03:15,040
There are a lot of things you can get notified about.

86
00:03:15,040 --> 00:03:18,680
A new user created in your tenant, a file updated in SharePoint,

87
00:03:18,680 --> 00:03:21,880
a message sent in Teams, a calendar event that changes,

88
00:03:21,880 --> 00:03:23,880
or a group that gets a new member.

89
00:03:23,880 --> 00:03:25,880
All of these can trigger a notification.

90
00:03:25,880 --> 00:03:28,840
Here's a real example, say you run a company with a time tracking system.

91
00:03:28,840 --> 00:03:32,120
When a new employee joins, you want to create an account automatically.

92
00:03:32,120 --> 00:03:36,560
Without web hooks, you pull the user's endpoint every few minutes checking for new people.

93
00:03:36,560 --> 00:03:39,600
With web hooks, you subscribe to user creation events.

94
00:03:39,600 --> 00:03:42,440
When someone joins, Graph sends your app a notification.

95
00:03:42,440 --> 00:03:45,640
Your app receives it, validates it, and creates the account.

96
00:03:45,640 --> 00:03:48,880
Or within seconds, no polling, no wasted requests.

97
00:03:48,880 --> 00:03:52,640
Another example, you have a SharePoint document library where receipts get uploaded.

98
00:03:52,640 --> 00:03:55,080
Without web hooks, you pull the library constantly.

99
00:03:55,080 --> 00:03:57,880
With web hooks, Graph tells you the moment a file is added.

100
00:03:57,880 --> 00:04:01,960
Your app grabs it, checks if it's a receipt, and processes it automatically.

101
00:04:01,960 --> 00:04:03,520
That's the power of web hooks.

102
00:04:03,520 --> 00:04:06,320
Instead of your app constantly asking anything new,

103
00:04:06,320 --> 00:04:08,240
you let the system tell you when something happens.

104
00:04:08,240 --> 00:04:11,720
It's more efficient, more reliable, and much faster.

105
00:04:11,720 --> 00:04:13,520
How Microsoft Graph Webhooks work.

106
00:04:13,520 --> 00:04:16,080
Now you know what web hooks are and why polling is the problem.

107
00:04:16,080 --> 00:04:18,800
Let's look at how Microsoft Graph Webhooks actually work,

108
00:04:18,800 --> 00:04:20,920
because the flow is simpler than you might think.

109
00:04:20,920 --> 00:04:26,040
It comes down to three things, a subscription, a notification, and your end point.

110
00:04:26,040 --> 00:04:28,720
First, you create a subscription, you tell Microsoft Graph,

111
00:04:28,720 --> 00:04:31,360
"Hey, I want to know when this specific thing changes."

112
00:04:31,360 --> 00:04:34,720
You give Graph the details of what to watch and where to send the news.

113
00:04:34,720 --> 00:04:36,520
Think of it like signing up for an alert.

114
00:04:36,520 --> 00:04:39,520
You tell the system what you care about and you give it your contact info.

115
00:04:39,520 --> 00:04:41,520
Second, Microsoft Graph watches that resource.

116
00:04:41,520 --> 00:04:42,520
It monitors for changes.

117
00:04:42,520 --> 00:04:46,640
When something happens, like a user created, a file updated, or a message arrives,

118
00:04:46,640 --> 00:04:47,640
Graph notices.

119
00:04:47,640 --> 00:04:49,360
Third, Graph sends a notification.

120
00:04:49,360 --> 00:04:52,080
It files off an HTTP post to the URL you provided.

121
00:04:52,080 --> 00:04:54,920
That post contains information about what changed.

122
00:04:54,920 --> 00:04:57,720
Your end point receives it and your application processes it.

123
00:04:57,720 --> 00:04:59,160
So the high level flow is simple.

124
00:04:59,160 --> 00:05:00,160
You subscribe.

125
00:05:00,160 --> 00:05:01,160
Graph watches.

126
00:05:01,160 --> 00:05:03,080
Graph sends a post when something changes.

127
00:05:03,080 --> 00:05:05,560
Let's break down those three building blocks a bit more.

128
00:05:05,560 --> 00:05:08,000
The subscription is your request to be alerted.

129
00:05:08,000 --> 00:05:12,040
It's like saying, "I want to know whenever a new user is added to my tenant."

130
00:05:12,040 --> 00:05:14,680
You send that request to Microsoft Graph and Graph stores it.

131
00:05:14,680 --> 00:05:17,360
From that point on, Graph is watching on your behalf.

132
00:05:17,360 --> 00:05:21,680
The notification is the alert itself, an HTTP post that Graph sends to your endpoint.

133
00:05:21,680 --> 00:05:25,760
The post body contains details about the change, like what resource changed, what type of change

134
00:05:25,760 --> 00:05:27,240
happened, and when it happened.

135
00:05:27,240 --> 00:05:29,240
Your endpoint is the door you leave open.

136
00:05:29,240 --> 00:05:32,600
It's a URL on your server, configured to receive these post requests.

137
00:05:32,600 --> 00:05:34,280
It just needs to listen and respond fast.

138
00:05:34,280 --> 00:05:35,280
That's it.

139
00:05:35,280 --> 00:05:37,560
No complex logic required at the receiving end.

140
00:05:37,560 --> 00:05:40,120
Just catch the notification, acknowledge it, and process it.

141
00:05:40,120 --> 00:05:41,520
Now compare this to polling.

142
00:05:41,520 --> 00:05:46,000
With polling, your app sends hundreds of get requests, each asking anything new.

143
00:05:46,000 --> 00:05:47,560
Most of the time the answer is no.

144
00:05:47,560 --> 00:05:49,280
With webhooks, there's just one post.

145
00:05:49,280 --> 00:05:50,280
The notification.

146
00:05:50,280 --> 00:05:51,280
That's it.

147
00:05:51,280 --> 00:05:52,280
One message instead of hundreds.

148
00:05:52,280 --> 00:05:56,560
The efficiency difference is enormous, and your endpoint doesn't need to be complicated.

149
00:05:56,560 --> 00:06:00,560
It just needs to be publicly accessible, speak HTTPS, and respond quickly.

150
00:06:00,560 --> 00:06:02,800
We'll talk about what quickly means in a bit.

151
00:06:02,800 --> 00:06:04,440
But the core idea is simple.

152
00:06:04,440 --> 00:06:09,560
Your endpoint listens, Graph calls, you respond, and done.

153
00:06:09,560 --> 00:06:10,560
Creating a subscription.

154
00:06:10,560 --> 00:06:12,720
So how do you actually set one of these up?

155
00:06:12,720 --> 00:06:15,280
Let's walk through creating a subscription step by step.

156
00:06:15,280 --> 00:06:19,640
You start by sending an HTTP post request to a specific URL on Microsoft Graph.

157
00:06:19,640 --> 00:06:21,440
That URL is HTTPS, Graph.

158
00:06:21,440 --> 00:06:24,400
Microsoft.com v1.0, subscriptions.

159
00:06:24,400 --> 00:06:26,880
You're posting straight to the subscriptions endpoint.

160
00:06:26,880 --> 00:06:30,720
Inside that request body, you include the details of what you want to subscribe to.

161
00:06:30,720 --> 00:06:32,560
There are four key fields you need to provide.

162
00:06:32,560 --> 00:06:34,240
First is notification URL.

163
00:06:34,240 --> 00:06:35,960
This is your endpoint's URL.

164
00:06:35,960 --> 00:06:38,560
The place where Microsoft Graph will send the notifications.

165
00:06:38,560 --> 00:06:41,800
It has to be HTTPS and it has to be publicly accessible because Graph needs to reach it

166
00:06:41,800 --> 00:06:42,800
from the internet.

167
00:06:42,800 --> 00:06:44,000
Second is resource.

168
00:06:44,000 --> 00:06:45,760
This tells Graph what you want to watch.

169
00:06:45,760 --> 00:06:47,920
You specify the Microsoft Graph resource path.

170
00:06:47,920 --> 00:06:53,040
For example, users if you want to watch for user changes or me, male folders, inbox messages

171
00:06:53,040 --> 00:06:55,400
if you want to watch for new emails in your inbox.

172
00:06:55,400 --> 00:06:57,680
The resource tells Graph exactly what you care about.

173
00:06:57,680 --> 00:06:59,400
Third is change type.

174
00:06:59,400 --> 00:07:02,440
This tells Graph what kind of changes to notify you about.

175
00:07:02,440 --> 00:07:05,880
You can specify created, updated, deleted, or any combination.

176
00:07:05,880 --> 00:07:09,640
So if you only care about new users being created, you set change type to create it.

177
00:07:09,640 --> 00:07:12,640
If you care about updates too, you set it to create it, updated.

178
00:07:12,640 --> 00:07:14,640
Fourth is expiration date time.

179
00:07:14,640 --> 00:07:18,000
This is when the subscription expires because subscriptions don't last forever.

180
00:07:18,000 --> 00:07:21,920
You set a date and time and Graph stops sending notifications after that point.

181
00:07:21,920 --> 00:07:24,640
The maximum duration depends on the resource you're watching.

182
00:07:24,640 --> 00:07:27,200
For users and groups, the max is about three days.

183
00:07:27,200 --> 00:07:30,760
For drive items in SharePoint or OneDrive, it can be up to 30 days.

184
00:07:30,760 --> 00:07:33,640
You need to check the documentation for each resource type.

185
00:07:33,640 --> 00:07:35,760
There's also an optional field worth mentioning.

186
00:07:35,760 --> 00:07:36,920
Client state.

187
00:07:36,920 --> 00:07:38,400
This is a secret string you create.

188
00:07:38,400 --> 00:07:39,960
It can be anything you want.

189
00:07:39,960 --> 00:07:42,320
A random string, a good, whatever you choose.

190
00:07:42,320 --> 00:07:46,560
Microsoft Graph includes this value in every notification it sends to your endpoint.

191
00:07:46,560 --> 00:07:50,560
And you use it to verify that the notification actually came from your subscription.

192
00:07:50,560 --> 00:07:54,400
If someone tries to send fake notifications to your endpoint, the client state won't match

193
00:07:54,400 --> 00:07:55,920
and you can reject it immediately.

194
00:07:55,920 --> 00:07:58,400
It's a simple security measure, but it's important.

195
00:07:58,400 --> 00:08:01,880
Creating a subscription is like signing up for a newspaper delivery.

196
00:08:01,880 --> 00:08:03,560
You give the newspaper your address.

197
00:08:03,560 --> 00:08:05,560
That's your notification URL.

198
00:08:05,560 --> 00:08:09,120
You tell them what sections you want, that's your resource and change type, and you tell

199
00:08:09,120 --> 00:08:11,320
them how long you want the delivery to continue.

200
00:08:11,320 --> 00:08:12,840
That's your expiration date time.

201
00:08:12,840 --> 00:08:14,320
The newspaper handles the rest.

202
00:08:14,320 --> 00:08:16,520
But here's the thing, subscriptions expire.

203
00:08:16,520 --> 00:08:19,000
You can't create one and forget about it.

204
00:08:19,000 --> 00:08:23,240
After the expiration date time passes, Graph stops sending notifications and your subscription

205
00:08:23,240 --> 00:08:24,240
is gone.

206
00:08:24,240 --> 00:08:27,400
If you want to keep receiving notifications, you need to renew the subscription before it

207
00:08:27,400 --> 00:08:31,120
expires by sending a patch request to the subscription endpoint with a new expiration

208
00:08:31,120 --> 00:08:32,120
date time.

209
00:08:32,120 --> 00:08:34,680
So creating a subscription is the first step, but it's not the last.

210
00:08:34,680 --> 00:08:36,080
You need to manage the life cycle.

211
00:08:36,080 --> 00:08:37,840
We'll talk more about that later.

212
00:08:37,840 --> 00:08:39,480
The validation handshake.

213
00:08:39,480 --> 00:08:42,800
Before your subscription goes live, there's one step you can't skip.

214
00:08:42,800 --> 00:08:46,800
Microsoft Graph doesn't just accept your subscription request and start sending notifications.

215
00:08:46,800 --> 00:08:50,360
It first needs to confirm your endpoint is real and ready to receive them.

216
00:08:50,360 --> 00:08:51,360
Here's how it works.

217
00:08:51,360 --> 00:08:55,120
When you send your post request to create a subscription, Microsoft Graph immediately fires

218
00:08:55,120 --> 00:08:57,960
off a test post to your notification URL.

219
00:08:57,960 --> 00:09:01,280
That test post includes a query parameter called validation token.

220
00:09:01,280 --> 00:09:02,600
It's just a random string.

221
00:09:02,600 --> 00:09:06,360
Your endpoint needs to grab that token and send it back as a plain text response and you

222
00:09:06,360 --> 00:09:08,160
have to do it within 10 seconds.

223
00:09:08,160 --> 00:09:10,240
Think of it like a courier delivering a package.

224
00:09:10,240 --> 00:09:12,840
They show up at your door and ask, is this the right address?

225
00:09:12,840 --> 00:09:13,840
Can you confirm?

226
00:09:13,840 --> 00:09:14,840
You have to sign for it.

227
00:09:14,840 --> 00:09:16,240
If you don't, they walk away.

228
00:09:16,240 --> 00:09:17,880
The courier doesn't leave the package.

229
00:09:17,880 --> 00:09:18,880
They just leave.

230
00:09:18,880 --> 00:09:20,600
But that's exactly what's happening here.

231
00:09:20,600 --> 00:09:24,240
Microsoft Graph is saying, I'm about to send you important notifications.

232
00:09:24,240 --> 00:09:27,880
Prove you're the right person at the right address.

233
00:09:27,880 --> 00:09:32,240
Your endpoint responds by echoing back the validation token, which tells Graph, yes,

234
00:09:32,240 --> 00:09:33,240
I'm here.

235
00:09:33,240 --> 00:09:34,240
I'm listening.

236
00:09:34,240 --> 00:09:35,800
Send me the notifications.

237
00:09:35,800 --> 00:09:38,160
Now here's where a lot of developers trip up.

238
00:09:38,160 --> 00:09:42,960
The validation token must be returned as plain text, not JSON, not HTML, plain text.

239
00:09:42,960 --> 00:09:46,400
And the response must have a content type header set to text plain.

240
00:09:46,400 --> 00:09:50,480
If you send it back wrapped in JSON or encoded in anyway, the validation fails.

241
00:09:50,480 --> 00:09:51,920
Your subscription won't be created.

242
00:09:51,920 --> 00:09:55,240
Microsoft Graph returns an error and you're stuck wondering what went wrong.

243
00:09:55,240 --> 00:09:57,040
There's another technical detail worth knowing.

244
00:09:57,040 --> 00:10:01,000
Microsoft Graph's validation service doesn't reliably support TLS 1.3.

245
00:10:01,000 --> 00:10:02,840
It negotiates TLS 1.2.

246
00:10:02,840 --> 00:10:07,560
So if your endpoint only accepts TLS 1.3 connections, the validation handshake fails before your

247
00:10:07,560 --> 00:10:09,360
application code even runs.

248
00:10:09,360 --> 00:10:14,760
You need to make sure your endpoint supports TLS 1.2, at least for the validation step.

249
00:10:14,760 --> 00:10:18,680
After that, you can enforce whatever TLS version you want for the actual notifications.

250
00:10:18,680 --> 00:10:21,840
The good news is this validation handshake only happens once per subscription.

251
00:10:21,840 --> 00:10:25,440
It's not something your endpoint has to handle every time a notification arrives, just the

252
00:10:25,440 --> 00:10:26,640
first time.

253
00:10:26,640 --> 00:10:31,200
Once Graph confirms your endpoint is real, it trusts it for the life of that subscription.

254
00:10:31,200 --> 00:10:33,960
So you only need to get this right once.

255
00:10:33,960 --> 00:10:35,760
Handling notifications and security.

256
00:10:35,760 --> 00:10:39,440
Once the validation handshake goes through and your subscription goes live, Microsoft Graph

257
00:10:39,440 --> 00:10:41,480
starts sending those notifications.

258
00:10:41,480 --> 00:10:43,880
So what do those actually look like in practice?

259
00:10:43,880 --> 00:10:48,720
When something changes, Graph sends an HTTP post to your endpoint with a JSON object in

260
00:10:48,720 --> 00:10:49,720
the body.

261
00:10:49,720 --> 00:10:53,480
That object contains the resource that changed the type of change that created, updated,

262
00:10:53,480 --> 00:10:55,480
or deleted, and a timestamp.

263
00:10:55,480 --> 00:10:59,360
It also includes the client state value you set when you created the subscription.

264
00:10:59,360 --> 00:11:02,240
That's your secret string your way of knowing the message is real.

265
00:11:02,240 --> 00:11:05,240
So here's the first thing to do when a notification arrives.

266
00:11:05,240 --> 00:11:06,560
Validate that client state.

267
00:11:06,560 --> 00:11:09,600
Compare the value in the notification against the secret you stored when you created the

268
00:11:09,600 --> 00:11:10,600
subscription.

269
00:11:10,600 --> 00:11:12,640
If they don't match, discard it immediately.

270
00:11:12,640 --> 00:11:14,000
Because it could be a fake.

271
00:11:14,000 --> 00:11:16,760
Someone trying to trick your system into processing bad data.

272
00:11:16,760 --> 00:11:19,480
This matters because your endpoint lives on the public internet.

273
00:11:19,480 --> 00:11:22,160
Anyone who knows your URL could send a post to it.

274
00:11:22,160 --> 00:11:25,480
Without client state validation, you'd have no way to tell the difference between a real

275
00:11:25,480 --> 00:11:28,280
Microsoft Graph notification and a fake one.

276
00:11:28,280 --> 00:11:30,640
It's a simple check, but it's your first line of defense.

277
00:11:30,640 --> 00:11:34,760
Once you've confirmed the notification is legit, you need to respond fast.

278
00:11:34,760 --> 00:11:38,440
Microsoft Graph expects a 200 level HTTP response within three seconds.

279
00:11:38,440 --> 00:11:42,720
If you take longer graph notices, and if it happens too often, graph starts treating you

280
00:11:42,720 --> 00:11:43,720
differently.

281
00:11:43,720 --> 00:11:44,720
Here's how the throttling works.

282
00:11:44,720 --> 00:11:49,720
If more than 10% of your responses exceed the three second window in any 10 minute period,

283
00:11:49,720 --> 00:11:51,960
Microsoft Graph marks your endpoint as slow.

284
00:11:51,960 --> 00:11:54,920
When that happens, new notifications get delayed by 10 minutes.

285
00:11:54,920 --> 00:11:58,120
They still arrive eventually, but you lose real time delivery.

286
00:11:58,120 --> 00:12:03,160
If things get worse, with more than 15% of your responses exceeding 10 seconds, graph marks

287
00:12:03,160 --> 00:12:04,680
your endpoint as drop.

288
00:12:04,680 --> 00:12:07,760
In that state, notifications are dropped entirely for 10 minutes.

289
00:12:07,760 --> 00:12:08,760
Here's the scary part.

290
00:12:08,760 --> 00:12:10,640
Drop notifications cannot be recovered.

291
00:12:10,640 --> 00:12:12,640
They're gone, and you'll never get them back.

292
00:12:12,640 --> 00:12:14,280
Think of it like a busy phone line.

293
00:12:14,280 --> 00:12:16,840
If you don't pick up quickly, the caller tries again later.

294
00:12:16,840 --> 00:12:19,800
But if you never pick up, eventually the caller gives up.

295
00:12:19,800 --> 00:12:23,120
Microsoft Graph is the caller, and your endpoint is the phone.

296
00:12:23,120 --> 00:12:25,120
You can't pick up fast or risk losing the message.

297
00:12:25,120 --> 00:12:26,920
So what's the best practice here?

298
00:12:26,920 --> 00:12:29,080
Acknowledge immediately and process asynchronously.

299
00:12:29,080 --> 00:12:34,080
Your endpoint should validate the client state, accept the notification, and return it 200 or

300
00:12:34,080 --> 00:12:36,160
202 responses as fast as possible.

301
00:12:36,160 --> 00:12:39,360
Then push the notification into a queue for background processing.

302
00:12:39,360 --> 00:12:42,480
And Azure queue, a service bus, even a simple database table.

303
00:12:42,480 --> 00:12:46,720
The point is to get out of the response cycle quickly and let your background workers handle

304
00:12:46,720 --> 00:12:47,720
the heavy lifting.

305
00:12:47,720 --> 00:12:50,520
And one more security reminder, your endpoint must be HTTPS.

306
00:12:50,520 --> 00:12:55,120
No exceptions, Microsoft Graph will not send notifications to an HTTP endpoint.

307
00:12:55,120 --> 00:12:58,480
And your endpoint must be publicly accessible if it's behind a firewall or a VPN Graph

308
00:12:58,480 --> 00:12:59,480
can't reach it.

309
00:12:59,480 --> 00:13:03,320
For development, you can use tools like en-groc to create a public tunnel to your local

310
00:13:03,320 --> 00:13:04,320
machine.

311
00:13:04,320 --> 00:13:08,840
But in production, your endpoint needs to live somewhere, Graph can find it.

312
00:13:08,840 --> 00:13:11,040
Keeping notifications alive, life cycle.

313
00:13:11,040 --> 00:13:15,000
So you've got your subscription setup, notifications are flowing, and everything looks good.

314
00:13:15,000 --> 00:13:17,280
But here's something that catches a lot of people off guard.

315
00:13:17,280 --> 00:13:19,000
Your subscription has an expiration date.

316
00:13:19,000 --> 00:13:21,880
It doesn't last forever, depending on what resource you're watching.

317
00:13:21,880 --> 00:13:25,200
The maximum subscription duration is usually between three and seven days.

318
00:13:25,200 --> 00:13:28,920
For some resources like drive items and SharePoint, you can get up to 30 days.

319
00:13:28,920 --> 00:13:30,640
But the point is, it's not permanent.

320
00:13:30,640 --> 00:13:33,280
You cannot create a subscription and forget about it.

321
00:13:33,280 --> 00:13:35,200
Think of it like a magazine subscription.

322
00:13:35,200 --> 00:13:38,040
You sign up, you start receiving issues and everything's great.

323
00:13:38,040 --> 00:13:41,320
But if you don't renew before the subscription runs out, the issue stops coming.

324
00:13:41,320 --> 00:13:42,320
Same thing here.

325
00:13:42,320 --> 00:13:45,560
If your subscription expires, Microsoft Graph stops sending notifications.

326
00:13:45,560 --> 00:13:48,480
And you might not realize it until you wonder why nothing's happening.

327
00:13:48,480 --> 00:13:51,040
So you need a renewal strategy, the way you renew is simple.

328
00:13:51,040 --> 00:13:55,320
Send a patch request to the subscription endpoint using the subscription ID and update the

329
00:13:55,320 --> 00:13:57,520
expiration date time to a new future date.

330
00:13:57,520 --> 00:13:59,560
That extends the life of the subscription.

331
00:13:59,560 --> 00:14:03,160
You can do this as many times as you want, as long as you do it before the current expiration

332
00:14:03,160 --> 00:14:04,160
passes.

333
00:14:04,160 --> 00:14:08,040
Now, Microsoft Graph actually helps you hear with something called life cycle notifications.

334
00:14:08,040 --> 00:14:12,200
When you create a subscription, you can provide a separate URL called the life cycle notification

335
00:14:12,200 --> 00:14:13,200
URL.

336
00:14:13,200 --> 00:14:17,080
Microsoft Graph sends alerts to that URL when certain things happen.

337
00:14:17,080 --> 00:14:20,960
Like when your subscription is about to expire, when your access token is about to run out,

338
00:14:20,960 --> 00:14:22,960
or when the permissions on your app change.

339
00:14:22,960 --> 00:14:25,080
These life cycle notifications give you a heads up.

340
00:14:25,080 --> 00:14:27,440
You don't have to guess when your subscription is going to die.

341
00:14:27,440 --> 00:14:30,500
Graph tells you, hey, your subscription expires in a few hours.

342
00:14:30,500 --> 00:14:32,000
You might want to renew.

343
00:14:32,000 --> 00:14:35,400
It's like getting a reminder from your magazine publisher that your subscription is about

344
00:14:35,400 --> 00:14:36,400
to end.

345
00:14:36,400 --> 00:14:38,000
Very helpful if you're paying attention.

346
00:14:38,000 --> 00:14:40,160
But what happens if things go wrong anyway?

347
00:14:40,160 --> 00:14:43,600
Maybe your endpoint goes down for a while or notifications get dropped because you were too

348
00:14:43,600 --> 00:14:44,600
slow.

349
00:14:44,600 --> 00:14:45,600
What then?

350
00:14:45,600 --> 00:14:46,600
That's where Delta query comes in.

351
00:14:46,600 --> 00:14:50,560
Delta query is a separate feature of Microsoft Graph that lets you ask, what changed since the

352
00:14:50,560 --> 00:14:51,960
last time I checked?

353
00:14:51,960 --> 00:14:54,200
And it returns only the changes, nothing else.

354
00:14:54,200 --> 00:14:55,200
Here's how it works.

355
00:14:55,200 --> 00:14:59,000
The first time you run a Delta query on a resource, say, users, graph returns all the users

356
00:14:59,000 --> 00:15:00,000
in your tenant.

357
00:15:00,000 --> 00:15:03,200
But it also returns something extra, a special link called a Delta link.

358
00:15:03,200 --> 00:15:04,200
You save that link.

359
00:15:04,200 --> 00:15:06,960
The next time you run the same query, you use that Delta link.

360
00:15:06,960 --> 00:15:10,880
And instead of getting all users again, you get only the ones that changed since your last

361
00:15:10,880 --> 00:15:11,880
request.

362
00:15:11,880 --> 00:15:14,160
New users, updated users, deleted users.

363
00:15:14,160 --> 00:15:15,640
That's it.

364
00:15:15,640 --> 00:15:19,360
Think of it like reading a what's new list instead of reading the entire encyclopedia every

365
00:15:19,360 --> 00:15:21,280
time, much faster, much less data.

366
00:15:21,280 --> 00:15:22,800
Now here's the smart pattern.

367
00:15:22,800 --> 00:15:24,680
Combine web hooks with Delta query.

368
00:15:24,680 --> 00:15:26,920
Use web hooks to tell you when something changed.

369
00:15:26,920 --> 00:15:29,480
Then use Delta query to find out exactly what changed.

370
00:15:29,480 --> 00:15:30,880
Let me explain why that matters.

371
00:15:30,880 --> 00:15:32,880
Web hooks are fast, but they're not perfect.

372
00:15:32,880 --> 00:15:33,880
Notifications can get lost.

373
00:15:33,880 --> 00:15:36,080
Subscriptions can expire and your endpoint can go down.

374
00:15:36,080 --> 00:15:37,320
But Delta query is reliable.

375
00:15:37,320 --> 00:15:38,680
You can run it any time.

376
00:15:38,680 --> 00:15:41,360
And it gives you a complete list of changes since your last check.

377
00:15:41,360 --> 00:15:44,520
So even if you miss a notification, you can catch up.

378
00:15:44,520 --> 00:15:45,920
And here's the typical flow.

379
00:15:45,920 --> 00:15:48,440
Set up a web hook subscription for user changes.

380
00:15:48,440 --> 00:15:52,040
Run an initial Delta query to get the baseline state and save the Delta link.

381
00:15:52,040 --> 00:15:55,880
When a web hook arrives telling you a user changed, run a Delta query using your saved

382
00:15:55,880 --> 00:15:56,880
Delta link.

383
00:15:56,880 --> 00:15:58,640
That gives you the exact change.

384
00:15:58,640 --> 00:15:59,640
Process it.

385
00:15:59,640 --> 00:16:01,280
Then save the new Delta link from that response.

386
00:16:01,280 --> 00:16:03,760
Next time a web hook comes in, repeat the process.

387
00:16:03,760 --> 00:16:08,040
And if you ever miss a notification or if your subscription expires, just run the Delta

388
00:16:08,040 --> 00:16:09,040
query again.

389
00:16:09,040 --> 00:16:10,360
You'll get everything you missed.

390
00:16:10,360 --> 00:16:11,360
It's a safety net.

391
00:16:11,360 --> 00:16:14,440
Web hooks give you speed and Delta query gives you reliability.

392
00:16:14,440 --> 00:16:17,080
Together, they're a powerful combination.

393
00:16:17,080 --> 00:16:19,160
Real world example and next steps.

394
00:16:19,160 --> 00:16:21,720
Imagine a new employee joins your company tomorrow.

395
00:16:21,720 --> 00:16:26,920
Someone in HR creates their account in Microsoft Entra ID and that single action kicks off

396
00:16:26,920 --> 00:16:28,120
a chain reaction.

397
00:16:28,120 --> 00:16:31,960
If you've set up a web hook subscription for user changes, Microsoft Graph notices instantly

398
00:16:31,960 --> 00:16:34,040
and fires a post to your endpoint.

399
00:16:34,040 --> 00:16:35,080
Here's what happens next.

400
00:16:35,080 --> 00:16:39,880
Your endpoint receives the notification, validates the client state, and if it matches your secret,

401
00:16:39,880 --> 00:16:41,160
you know it's legit.

402
00:16:41,160 --> 00:16:46,320
To return a 202 accepted response within three seconds, acknowledging the notification,

403
00:16:46,320 --> 00:16:48,040
and then your background worker picks it up.

404
00:16:48,040 --> 00:16:51,680
The worker Caesar user was created, but the notification doesn't include all the details,

405
00:16:51,680 --> 00:16:54,440
so it runs a Delta query using your saved Delta link.

406
00:16:54,440 --> 00:16:59,160
That returns the new user's full information, name, email, department, job title, manager,

407
00:16:59,160 --> 00:17:00,280
everything you need.

408
00:17:00,280 --> 00:17:03,880
Now your worker takes that information and creates an account for the new employee in

409
00:17:03,880 --> 00:17:05,680
your third party time tracking system.

410
00:17:05,680 --> 00:17:06,760
It sends a welcome email.

411
00:17:06,760 --> 00:17:09,360
It adds them to the appropriate distribution lists.

412
00:17:09,360 --> 00:17:14,040
All of this happens within seconds of HR creating the account in Entra ID, no polling,

413
00:17:14,040 --> 00:17:16,640
no manual steps, no delays.

414
00:17:16,640 --> 00:17:17,960
Think about the alternative.

415
00:17:17,960 --> 00:17:21,840
Without web hooks, you'd have to poll the user's endpoint every few minutes, hundreds of requests

416
00:17:21,840 --> 00:17:25,600
per day, and even then you might not catch the new user for several minutes.

417
00:17:25,600 --> 00:17:27,040
With web hooks, it's instant.

418
00:17:27,040 --> 00:17:29,280
One notification, one Delta query done.

419
00:17:29,280 --> 00:17:30,280
That's the real value.

420
00:17:30,280 --> 00:17:34,280
Your system becomes faster, more efficient, and less likely to hit throttling limits.

421
00:17:34,280 --> 00:17:38,200
Instead of constantly asking Graph for updates, you let Graph tell you when something happens.

422
00:17:38,200 --> 00:17:40,840
It's a fundamental shift in how you build integrations.

423
00:17:40,840 --> 00:17:42,200
So here's what I want you to try.

424
00:17:42,200 --> 00:17:44,760
Think about one process you're currently polling for.

425
00:17:44,760 --> 00:17:47,120
Maybe you're checking for new emails in a shared mailbox.

426
00:17:47,120 --> 00:17:50,160
Maybe you're watching for file changes in a SharePoint library.

427
00:17:50,160 --> 00:17:54,320
Maybe your monitoring user updates for your HR system could a web hook replace that polling?

428
00:17:54,320 --> 00:17:56,240
In most cases, the answer is yes.

429
00:17:56,240 --> 00:17:57,920
And you don't need to build everything from scratch.

430
00:17:57,920 --> 00:18:01,680
Tools like Azure Functions can host your web hook endpoint with minimal code.

431
00:18:01,680 --> 00:18:05,760
Power Automate can handle subscriptions and notifications without writing a single line.

432
00:18:05,760 --> 00:18:07,720
Even logic apps can process web hook payloads.

433
00:18:07,720 --> 00:18:08,800
The infrastructure is there.

434
00:18:08,800 --> 00:18:10,640
You just need to use it.

435
00:18:10,640 --> 00:18:12,520
So here's the core idea in plain English.

436
00:18:12,520 --> 00:18:13,520
Stop polling.

437
00:18:13,520 --> 00:18:14,520
Start listening.

438
00:18:14,520 --> 00:18:18,640
Web hooks let you move from constantly asking Microsoft Graph for updates to getting notified

439
00:18:18,640 --> 00:18:20,680
instantly when something changes.

440
00:18:20,680 --> 00:18:25,000
That shift transforms your system from one that wastes, calls, and risks throttling to one

441
00:18:25,000 --> 00:18:27,080
that's fast, efficient, and reliable.

442
00:18:27,080 --> 00:18:31,840
Instead of thousands of unnecessary requests per day, you get one notification per change.

443
00:18:31,840 --> 00:18:34,680
Instead of waiting minutes to find out about an update, you know, within seconds.

444
00:18:34,680 --> 00:18:38,840
Instead of worrying about hitting GraphJail, you work within the system the way it was designed.

445
00:18:38,840 --> 00:18:43,400
So if you're building integrations with Microsoft 365, web hooks are the smarter path.

446
00:18:43,400 --> 00:18:44,800
They make your system faster.

447
00:18:44,800 --> 00:18:47,040
They make it less likely to be throttled.

448
00:18:47,040 --> 00:18:49,880
And they give you real time awareness of what's happening in your tenant.

449
00:18:49,880 --> 00:18:52,520
That's it for this episode of Microsoft Knowledge Nuggets.

450
00:18:52,520 --> 00:18:56,160
Subscribe on your favorite podcast platform and share this with someone starting their journey

451
00:18:56,160 --> 00:18:57,360
with Microsoft Graph.

452
00:18:57,360 --> 00:18:58,360
I'm Mirko Peters.