Test DocuSign Connect webhooks locally

Start your appCopy Anchor Link

When you turn on HMAC for a Connect configuration, DocuSign computes an HMAC-SHA256 (a keyed hash) of the raw request body with your secret key. It Base64-encodes the result and sends it in X-DocuSign-Signature-1. If you have several active keys, DocuSign sends one header per key: X-DocuSign-Signature-2, and so on. A delivery is valid when any one of them matches your key.

Create a route handler. Read the raw body with request.text(). Don't parse it first, because the signature covers the exact bytes.

import { createHmac, timingSafeEqual } from "node:crypto";

const SIGNATURE_HEADER_PREFIX = "x-docusign-signature-";

export async function POST(request: Request) {
  const secret = process.env.DOCUSIGN_CONNECT_HMAC_KEY;
  if (!secret) {
    return new Response("Missing DOCUSIGN_CONNECT_HMAC_KEY", { status: 500 });
  }

  const body = await request.text();
  const expected = createHmac("sha256", secret).update(body).digest();

  const signatures = [...request.headers]
    .filter(([name]) => name.startsWith(SIGNATURE_HEADER_PREFIX))
    .map(([, value]) => Buffer.from(value, "base64"));

  const isValid = signatures.some(
    (signature) =>
      signature.length === expected.length && timingSafeEqual(signature, expected),
  );

  if (!isValid) {
    return new Response("Invalid signature", { status: 401 });
  }

  const payload = JSON.parse(body);
  console.log(`Received DocuSign event: ${payload.event}`);

  return new Response("ok", { status: 200 });
}

Reply with 200 quickly. DocuSign logs a failure for any other status.

You get the key in a later step. Add it to .env.local once you have it:

DOCUSIGN_CONNECT_HMAC_KEY=replace-with-your-connect-key

Start the app:

npm run dev

Start a tunnelCopy Anchor Link

In a second terminal, open a tunnel to port 3000 on a subdomain you reserved, with -s:

hrzn tunnel http://localhost:3000 -s my-docusign-app

HORIZON: Tunnel connected
  URL          https://my-docusign-app.hrzn.run (reserved)
  Forwarding   http://localhost:3000
  Request log  https://hrzn.run/dashboard/tunnels/my-docusign-app

Your public URL is https://my-docusign-app.hrzn.run. Without -s the subdomain is random and changes on every run, so your Connect configuration would point at a dead URL after a restart. Reserved subdomains are a paid feature, see Pricing.

Create a Connect keyCopy Anchor Link

1. Sign in to DocuSign and open Settings.
2. Under Integrations, select Connect.
3. Select Connect Keys.
4. Select Add Secret Key.
5. Copy the key into .env.local as DOCUSIGN_CONNECT_HMAC_KEY, then restart npm run dev.

DocuSign shows the key value only when you create it. Copy it now.

Add the Connect configurationCopy Anchor Link

Your endpoint URL is the tunnel URL plus the route path: https://my-docusign-app.hrzn.run/api/webhooks/docusign.

1. On the Connect page, select Add Configuration, then Custom.
2. Enter a name for the configuration.
3. Enter the endpoint URL as URL to Publish.
4. Select Include HMAC Signature.
5. Select the envelope events you want, and choose JSON as the data format. The handler parses JSON.
6. Save the configuration.

Trigger an eventCopy Anchor Link

Send an envelope from your demo account and complete it. DocuSign then posts the matching event to your URL.

To resend an event, open Settings, Connect, then Publish. DocuSign lists envelopes with recent events there, and an admin can republish them. This works for deliveries that failed, or for envelopes you want to send again.