Cookbook
Archive signed documents to SharePoint
Upload the signed PDF to a SharePoint document library through Microsoft Graph with app-only authentication when a deliverable is generated.
Keep a copy of every signed document in a SharePoint document library. When deliverable.generated arrives, the handler gets a Microsoft Graph token as your app and uploads the PDF by path.
What you need
- A webhook endpoint subscribed to
deliverable.generated(set up webhooks). - A Microsoft Entra app registration with a client secret, and an administrator-granted application permission on Microsoft Graph.
SIGNATUREAPI_KEY,SIGNATUREAPI_WEBHOOK_SECRET,AZURE_TENANT_ID,AZURE_CLIENT_ID,AZURE_CLIENT_SECRETandSHAREPOINT_SITE_ID.
The handler
The sample uses the site’s default document library and uploads with a single PUT for files up to 250 MB. A longer sample for larger files follows the notes.
// npm install express standardwebhooks @azure/msal-node
import express from "express";
import { Webhook } from "standardwebhooks";
import { ConfidentialClientApplication } from "@azure/msal-node";
const msal = new ConfidentialClientApplication({
auth: {
clientId: process.env.AZURE_CLIENT_ID,
clientSecret: process.env.AZURE_CLIENT_SECRET,
authority: `https://login.microsoftonline.com/${process.env.AZURE_TENANT_ID}`,
},
});
const app = express();
app.post("/webhooks/signatureapi", express.raw({ type: "application/json" }), async (req, res) => {
let event;
try {
event = new Webhook(process.env.SIGNATUREAPI_WEBHOOK_SECRET).verify(
req.body.toString("utf8"),
req.headers,
);
} catch {
return res.sendStatus(400);
}
if (event.type !== "deliverable.generated") return res.sendStatus(200);
const { object_id: deliverableId, envelope_id: envelopeId } = event.data;
// The link in the event expires after 1 hour, so fetch a fresh one.
const api = await fetch(`https://api.signatureapi.com/v1/deliverables/${deliverableId}`, {
headers: { "X-API-Key": process.env.SIGNATUREAPI_KEY },
});
const { url } = await api.json();
const pdf = Buffer.from(await (await fetch(url)).arrayBuffer());
const { accessToken } = await msal.acquireTokenByClientCredential({
scopes: ["https://graph.microsoft.com/.default"],
});
const path = `signed/${envelopeId}/${deliverableId}.pdf`;
const upload = await fetch(
`https://graph.microsoft.com/v1.0/sites/${process.env.SHAREPOINT_SITE_ID}/drive/root:/${path}:/content`,
{
method: "PUT",
headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/pdf" },
body: pdf,
},
);
if (!upload.ok) return res.sendStatus(500);
res.sendStatus(200);
});
app.listen(3000);# pip install flask standardwebhooks requests msal
import os
import msal
import requests
from flask import Flask, request
from standardwebhooks import Webhook
graph_app = msal.ConfidentialClientApplication(
os.environ["AZURE_CLIENT_ID"],
client_credential=os.environ["AZURE_CLIENT_SECRET"],
authority=f'https://login.microsoftonline.com/{os.environ["AZURE_TENANT_ID"]}',
)
app = Flask(__name__)
@app.post("/webhooks/signatureapi")
def handle():
try:
event = Webhook(os.environ["SIGNATUREAPI_WEBHOOK_SECRET"]).verify(
request.get_data(), dict(request.headers)
)
except Exception:
return "", 400
if event["type"] != "deliverable.generated":
return "", 200
deliverable_id = event["data"]["object_id"]
envelope_id = event["data"]["envelope_id"]
# The link in the event expires after 1 hour, so fetch a fresh one.
api = requests.get(
f"https://api.signatureapi.com/v1/deliverables/{deliverable_id}",
headers={"X-API-Key": os.environ["SIGNATUREAPI_KEY"]},
)
pdf = requests.get(api.json()["url"]).content
token = graph_app.acquire_token_for_client(scopes=["https://graph.microsoft.com/.default"])
path = f"signed/{envelope_id}/{deliverable_id}.pdf"
upload = requests.put(
f'https://graph.microsoft.com/v1.0/sites/{os.environ["SHAREPOINT_SITE_ID"]}/drive/root:/{path}:/content',
headers={
"Authorization": f'Bearer {token["access_token"]}',
"Content-Type": "application/pdf",
},
data=pdf,
)
return "", (200 if upload.ok else 500)- Verify the signature over the raw body, as in verify the signature. Returning a non-2XX status makes SignatureAPI retry, for up to 48 hours.
- The same event can arrive more than once. The path combines the envelope id and the deliverable id, so a retry targets the same file.
- Both samples upload inline for brevity. For large volumes, acknowledge the event and move the upload to a job.
- MSAL’s client credentials scope is always
https://graph.microsoft.com/.default: it returns the application permissions an administrator granted. MSAL Python caches this token; the sample calls it on every event. - Microsoft documents
Files.ReadWrite.Allas the least privileged application permission for the simple upload, andSites.ReadWrite.Allfor upload sessions. Both reach every site. To limit the app to one site, useSites.Selected: it starts with no access, and an administrator then grants your app a role such aswriteon the site withPOST /sites/{siteId}/permissions. Granting it needsSites.FullControl.All, orSites.Selectedwith thefullcontrolorownerrole. Test the upload with the exact permission you plan to ship. - Replacing the contents of a file protected with a sensitivity label does not work with app-only authentication.
Files over 250 MB
PUT .../content only supports files up to 250 MB. For larger files, create an upload session and send the bytes to the uploadUrl in ranges. Microsoft recommends sessions above 10 MiB, with ranges that are multiples of 320 KiB and under 60 MiB.
const session = await fetch(
`https://graph.microsoft.com/v1.0/sites/${siteId}/drive/root:/${path}:/createUploadSession`,
{
method: "POST",
headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
body: JSON.stringify({ item: { "@microsoft.graph.conflictBehavior": "replace" } }),
},
);
const { uploadUrl } = await session.json();
const chunk = 320 * 1024 * 30; // 9.375 MiB, a multiple of 320 KiB
for (let start = 0; start < pdf.length; start += chunk) {
const end = Math.min(start + chunk, pdf.length);
// No Authorization header here: the uploadUrl is pre-authenticated.
const res = await fetch(uploadUrl, {
method: "PUT",
headers: { "Content-Range": `bytes ${start}-${end - 1}/${pdf.length}` },
body: pdf.subarray(start, end),
});
if (!res.ok) throw new Error(`Upload failed at byte ${start}: ${res.status}`);
}Send ranges in order. The last range returns 201 Created or 200 OK. conflictBehavior defaults to fail for upload sessions, so the sample sets replace to stay idempotent.