📝Signing requests

What it does

A SigningRequest is a server-stored record of 'this payload, signed by this email, by this time'. The signer hits a hosted page that walks them through key selection, signing in-browser (no plaintext key ever leaves), and finally the server re-verifies the Ed25519 signature before storing it.

How it works

1. 1

   Your backend POSTs to /api/signing-requests with the payload hash and target email. Bearer-auth with an API key.

2. 2

   DocSign returns a signLink and (optionally) a callbackSecret for HMAC-verifying the webhook later.

3. 3

   Forward the signLink to the signer; they open it, optionally log in, and click Sign.

4. 4

   DocSign re-verifies the Ed25519 signature server-side before storing.

5. 5

   Your callbackUrl receives an HMAC-SHA-256-signed JSON payload with the signature and signer metadata.

Why it matters

• ✓The same flow works for human signers (your invoice approval) and machine-to-machine handshakes.
• ✓Webhook HMAC = HMAC-SHA-256 over the raw body — easy to verify in any language.
• ✓Signing-request status survives webhook delivery failures: you can always poll GET /api/signing-requests/{id}.

Create a signing request

Copy-paste starting point for integrating this feature.

curl -X POST https://docsign.example.com/api/signing-requests \
  -H "authorization: Bearer dsk_..." \
  -H "content-type: application/json" \
  -d '{
    "targetEmail": "ada@example.com",
    "payloadHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "payloadPreview": "Sign invoice #4711",
    "callbackUrl": "https://yourapp.com/hooks/docsign",
    "expiresInMinutes": 60
  }'

Related features