microsoft-sharepoint-webhooks

Microsoft SharePoint Webhooks

When to Use This Skill

• Setting up Microsoft SharePoint list or document-library webhook handlers
• Completing the SharePoint validationtoken subscription handshake
• Validating the clientState shared secret on incoming notifications
• Understanding the thin SharePoint notification payload
• Reacting to list-item changes (ItemAdded, ItemUpdated, ItemDeleted) via the GetChanges API

How SharePoint Webhooks Differ

SharePoint webhooks are not HMAC-signed and are not Standard Webhooks. There is no request signature. Authenticity relies on two things instead:

1. Validation handshake — when a subscription is created (or its notificationUrl changes), SharePoint POSTs with a validationtoken query-string parameter. Your endpoint must echo that exact token back as an HTTP 200 text/plain body within ~5 seconds, or the subscription is never created.
2. clientState — an opaque string you set at subscription time. SharePoint echoes it in the clientState field of every notification. Compare it to your stored secret as a shared-secret sanity check. It is the only per-message identity signal (not a signature).

Notifications are thin and batched under a value array and carry no change details — you call the list GetChanges API with a stored change token to learn what actually changed.

Verification (core)

const crypto = require('crypto');

// 1. Validation handshake — runs BEFORE any body parsing.
//    Echo the validationtoken query param back verbatim as text/plain.
const token = new URL(req.url, 'http://localhost').searchParams.get('validationtoken');
if (token) {
  res.setHeader('Content-Type', 'text/plain');
  return res.status(200).send(token);   // must reply within ~5s or creation fails
}

// 2. clientState — timing-safe compare the shared secret on every notification.
function clientStateMatches(received, expected) {
  if (typeof received !== 'string' || typeof expected !== 'string') return false;
  const a = Buffer.from(received);
  const b = Buffer.from(expected);
  if (a.length !== b.length) return false;
  return crypto.timingSafeEqual(a, b);
}

const { value = [] } = JSON.parse(rawBody);   // thin, batched notifications
const ok = value.every(n => clientStateMatches(n.clientState, process.env.SHAREPOINT_CLIENT_STATE));
if (!ok) return res.status(400).send('Invalid clientState');
// Notifications carry no change details — call list GetChanges with your stored change token.