Cookbook
Archive signed documents to Amazon S3 with Object Lock
Store each signed PDF in an Amazon S3 bucket with Object Lock retention when SignatureAPI sends a deliverable.generated event.
Keep a write-once copy of every signed document in your own Amazon S3 bucket. The handler verifies the webhook, fetches a fresh download link, and puts the PDF in the bucket with a retention date.
What you need
- A webhook endpoint subscribed to
deliverable.generated. See Set up webhooks. - An S3 bucket created with Object Lock enabled. AWS requires S3 Versioning and Object Lock on the bucket before you lock any object, and you cannot disable either afterwards. Create the bucket this way from the start, for example with
aws s3api create-bucket --bucket <name> --object-lock-enabled-for-bucket. Source: Configuring S3 Object Lock. - Environment variables
SIGNATUREAPI_KEY,SIGNATUREAPI_WEBHOOK_SECRET,S3_BUCKET, and AWS credentials and region the SDK can find.
The handler
Node.js
import express from "express";
import { Webhook } from "standardwebhooks";
import { S3Client, HeadObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";
const s3 = new S3Client({});
const wh = new Webhook(process.env.SIGNATUREAPI_WEBHOOK_SECRET);
const app = express();
app.post("/webhooks/signatureapi", express.raw({ type: "application/json" }), async (req, res) => {
let event;
try {
event = wh.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;
const Key = `signed/${envelopeId}/${deliverableId}.pdf`;
const Bucket = process.env.S3_BUCKET;
try {
await s3.send(new HeadObjectCommand({ Bucket, Key }));
return res.sendStatus(200); // already archived
} catch (err) {
if (err.$metadata?.httpStatusCode !== 404) throw err;
}
// 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 deliverable = await api.json();
const pdf = Buffer.from(await (await fetch(deliverable.url)).arrayBuffer());
const retainUntil = new Date();
retainUntil.setFullYear(retainUntil.getFullYear() + 7);
await s3.send(new PutObjectCommand({
Bucket,
Key,
Body: pdf,
ContentType: "application/pdf",
ChecksumAlgorithm: "SHA256",
ObjectLockMode: "COMPLIANCE",
ObjectLockRetainUntilDate: retainUntil,
}));
res.sendStatus(200);
});
app.listen(3000);Python
import os
from datetime import datetime, timedelta, timezone
import boto3
import requests
from botocore.exceptions import ClientError
from flask import Flask, request
from standardwebhooks import Webhook
s3 = boto3.client("s3")
wh = Webhook(os.environ["SIGNATUREAPI_WEBHOOK_SECRET"])
app = Flask(__name__)
@app.post("/webhooks/signatureapi")
def handle():
try:
event = wh.verify(request.get_data(), dict(request.headers))
except Exception:
return "", 400
if event["type"] != "deliverable.generated":
return "", 200
deliverable_id = event["data"]["object_id"]
key = f"signed/{event['data']['envelope_id']}/{deliverable_id}.pdf"
bucket = os.environ["S3_BUCKET"]
try:
s3.head_object(Bucket=bucket, Key=key)
return "", 200 # already archived
except ClientError as err:
if err.response["Error"]["Code"] != "404":
raise
# 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"]},
)
api.raise_for_status()
pdf = requests.get(api.json()["url"]).content
s3.put_object(
Bucket=bucket,
Key=key,
Body=pdf,
ContentType="application/pdf",
ChecksumAlgorithm="SHA256",
ObjectLockMode="COMPLIANCE",
ObjectLockRetainUntilDate=datetime.now(timezone.utc) + timedelta(days=7 * 365),
)
return "", 200- Verify first. Verification needs the raw request body, so the Node handler uses
express.rawand the Python handler usesrequest.get_data(). See verify the signature. - Retries and duplicates. SignatureAPI retries a non-2XX response for up to 48 hours, and the same event can arrive more than once. The key is derived from the envelope and deliverable ids, so a repeat maps to the same object. A versioned bucket keeps a new version for every
PutObjecton the same key, so the handler checks withHeadObjectfirst. Two deliveries at the same moment can both pass the check and write two identical versions. - Retention.
COMPLIANCEmode means no user, including the AWS account root user, can overwrite or delete the object version until the retain-until date, and the date cannot be shortened. InGOVERNANCEmode users with special permissions can change the retention or delete the object. AWS suggests governance mode to test retention settings first. Source: Retention modes. - Checksum. AWS documents that
Content-MD5orx-amz-sdk-checksum-algorithmis required on any upload that sets a retention period.ChecksumAlgorithmsets the second header. Source: PutObject. - Bucket default instead. To skip the per-object settings, set a default retention on the bucket (a mode plus days or years). An object put with its own mode and date overrides the default. Source: Configuring S3 Object Lock.
- Slow work. Respond 2XX quickly. For large documents, queue the upload in a job and return right away.
Related
- Webhooks
- Deliverable events
- Retrieve a deliverable
- Locking objects with Object Lock (Amazon S3 User Guide)