Skip to content

Cookbook

Archive signed documents to Dropbox or Box

Upload the signed PDF to Dropbox or Box when a deliverable is generated, with a Node.js handler for each service.

Keep a copy of every signed document in Dropbox or Box. When deliverable.generated arrives, the handler fetches the signed PDF and uploads it. Pick the tab for your service.

What you need

  • A webhook endpoint subscribed to deliverable.generated (set up webhooks).
  • SIGNATUREAPI_KEY and SIGNATUREAPI_WEBHOOK_SECRET.
  • Dropbox: an app with the files.content.write scope, plus DROPBOX_APP_KEY, DROPBOX_APP_SECRET and DROPBOX_REFRESH_TOKEN.
  • Box: a Custom App using Client Credentials Grant, plus BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID and BOX_FOLDER_ID.

The handler

Dropbox
// npm install express standardwebhooks dropbox
import express from "express";
import { Webhook } from "standardwebhooks";
import { Dropbox } from "dropbox";

const dbx = new Dropbox({
  clientId: process.env.DROPBOX_APP_KEY,
  clientSecret: process.env.DROPBOX_APP_SECRET,
  refreshToken: process.env.DROPBOX_REFRESH_TOKEN,
});

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());

  // Overwrite keeps a retried event from creating a second copy.
  await dbx.filesUpload({
    path: `/signed/${envelopeId}_${deliverableId}.pdf`,
    contents: pdf,
    mode: { ".tag": "overwrite" },
  });
  res.sendStatus(200);
});

app.listen(3000);
Box
// npm install express standardwebhooks
import express from "express";
import { Webhook } from "standardwebhooks";

// Client Credentials Grant as the app's service account. Tokens last 60 minutes.
async function boxToken() {
  const res = await fetch("https://api.box.com/oauth2/token", {
    method: "POST",
    body: new URLSearchParams({
      grant_type: "client_credentials",
      client_id: process.env.BOX_CLIENT_ID,
      client_secret: process.env.BOX_CLIENT_SECRET,
      box_subject_type: "enterprise",
      box_subject_id: process.env.BOX_ENTERPRISE_ID,
    }),
  });
  return (await res.json()).access_token;
}

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 = await (await fetch(url)).blob();

  // Box requires "attributes" before "file" in the form.
  const form = new FormData();
  form.append(
    "attributes",
    JSON.stringify({
      name: `${envelopeId}_${deliverableId}.pdf`,
      parent: { id: process.env.BOX_FOLDER_ID },
    }),
  );
  form.append("file", pdf, "signed.pdf");

  const upload = await fetch("https://upload.box.com/api/2.0/files/content", {
    method: "POST",
    headers: { Authorization: `Bearer ${await boxToken()}` },
    body: form,
  });
  // 409: a file with this name already exists in the folder (a retried event).
  if (!upload.ok && upload.status !== 409) return res.sendStatus(500);
  res.sendStatus(200);
});

app.listen(3000);
  • 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. Both handlers name the file after the envelope id and the deliverable id, so a retry lands on the same name.
  • Both samples upload inline for brevity. For large volumes, acknowledge the event and move the upload to a job.
  • Dropbox: one files/upload request carries at most 150 MiB. Beyond that, use upload sessions (filesUploadSessionStart, filesUploadSessionAppendV2, filesUploadSessionFinish). The SDK package is dropbox (checked on 10.x).
  • Dropbox: the SDK exchanges the refresh token for short-lived access tokens, so the handler needs no token code.
  • Box: direct upload is limited to 50 MB, and Box rejects the Chunked Upload API for files under 20 MB. Box documents 409 for a name that already exists and for an account out of disk space. The sample treats every 409 as a duplicate, so log the response body if you need to tell them apart.