DocuSign Connect webhook payload example (envelope-completed)

DocuSign · event: envelope-completed (Connect 2.0 / JSON SIM) · content type: application/json

This is a representative sample — fake IDs, real structure. To see a payload with your data, point the provider at a capture URL (button below).

Headers

content-type: application/json
x-docusign-signature-1: 6ENjI1O3fangjNnblmEG6rppVtItKBNRgJmdmf6U0UM=
x-authorization-digest: HMACSHA256

Body

{
  "event": "envelope-completed",
  "apiVersion": "v2.1",
  "uri": "/restapi/v2.1/accounts/8fa9c2e1-5c7b-4a0d-9e3f-2b6d81c4a7f0/envelopes/1d5e0f3a-92b7-4c48-a6d1-7e9f30b2c5a8",
  "retryCount": 0,
  "configurationId": 12873452,
  "generatedDateTime": "2026-08-30T11:21:57.8437219Z",
  "data": {
    "accountId": "8fa9c2e1-5c7b-4a0d-9e3f-2b6d81c4a7f0",
    "userId": "6f2a9c81-3d5e-47b0-8a1c-95e7d20b4f63",
    "envelopeId": "1d5e0f3a-92b7-4c48-a6d1-7e9f30b2c5a8"
  }
}

Things that bite people

• This example's signature actually verifies — and it's base64, not hex. X-DocuSign-Signature-1 = base64 HMAC-SHA256 over the raw body (secret here: hookden-docusign-sample-hmac-key). Try it in the signature debugger (DocuSign provider), or set scheme "Generic HMAC" with header x-docusign-signature-1 on a capture bin — the bin compares hex and base64, so the ✓/✗ badge works live. Verifiers that hex-encode the digest (the GitHub habit) never match — that's the top DocuSign verification bug. x-authorization-digest: HMACSHA256 names the algorithm on every delivery.
• One header per key, up to one hundred keys. Define 2 HMAC keys in the Connect config and every message carries X-DocuSign-Signature-1 and -2 (in key order). Docs: matching any one of them is sufficient. Two quirks straight from DocuSign's own validation page: hash the entire body including line endings, and if the secret contains " characters, remove them before computing. Their own how-to blog even says to grab the test bytes from a capture tool — with pretty-printing turned off, because formatted bytes ≠ signed bytes.
• The default JSON SIM payload is this thin. No document, no recipients, no status history — just event + IDs (envelope data lives behind the uri). If you expected the legacy envelope summary, subscribe with includeData (tabs/recipients/documents…) — but DocuSign warns bigger payloads deliver slower. Workflows keyed on "status": "sent" must key on "event": "envelope-sent" in JSON SIM — handlers deserializing the old shape silently read nothing.
• Success = HTTP 200 within 100 seconds (with Require Acknowledgment on) — the most generous deadline of any provider we cover (Sentry gives you 1s). Failures retry with exponential back-off: 5m → 10m → 20m → 40m → 1h → 2h → … → 1 day, then once per day for 15 days — the longest retry tail we know of. retryCount in the payload tells you which attempt you're looking at. Envelopes queue separately: envelope A failing doesn't block envelope B.
• Endpoints that keep failing deactivate on a timetable: failing "nearly every time" for 3 days → status Active - Pending Deactivation; after 14+ days → System Deactivated, and new events stop. Admins get three warning emails along the way. Forgotten test configurations are the classic victim — reactivate from the Connect page after fixing the endpoint.
• Local dev: DocuSign Connect only delivers to public HTTPS endpoints. Point it at a capture bin and relay to localhost — bodies are byte-identical, so the HMAC above still verifies downstream.

Send it yourself

Reproduce this delivery against any endpoint (your handler, a bin, staging):

$ curl -X POST https://your-endpoint.example/hook \
  -H 'content-type: application/json' \
  -H 'x-docusign-signature-1: 6ENjI1O3fangjNnblmEG6rppVtItKBNRgJmdmf6U0UM=' \
  -H 'x-authorization-digest: HMACSHA256' \
 -d '{
  "event": "envelope-completed",
  "apiVersion": "v2.1",
  "uri": "/restapi/v2.1/accounts/8fa9c2e1-5c7b-4a0d-9e3f-2b6d81c4a7f0/envelopes/1d5e0f3a-92b7-4c48-a6d1-7e9f30b2c5a8",
  "retryCount": 0,
  "configurationId": 12873452,
  "generatedDateTime": "2026-08-30T11:21:57.8437219Z",
  "data": {
    "accountId": "8fa9c2e1-5c7b-4a0d-9e3f-2b6d81c4a7f0",
    "userId": "6f2a9c81-3d5e-47b0-8a1c-95e7d20b4f63",
    "envelopeId": "1d5e0f3a-92b7-4c48-a6d1-7e9f30b2c5a8"
  }
}'

← All payload examples · Signature debugger · Docs