Flowgrammer

DocuSign E-Signature Automation

Verify DocuSign Connect HMAC on the exact raw body, handle rotating Signature-N keys, and keep vendor routing from becoming Flowgrammer Document Approval.

— Craig Major

You can verify a DocuSign Connect notification on the exact raw body, accept any matching X-Docusign-Signature-N key, ACK quickly, and queue the rest. The published E-Signature Automation guide owns the shared Signing Control Plane. This page is the DocuSign adapter: envelopeId, Connect HMAC, routingOrder, and listAuditEvents. The DocuSign Connect Webhook Test Pack gives you fiction fixtures for those checks.

Start from the Signing Workflow Requirements Workbook if you still need the shared field list. If the missing job is a named approve, reject, or request-changes decision, use the published Document Approval Workflow. A completed envelope is not that decision. This page covers the eSignature Connect adapter. Recipient signing order and Approve/Decline actions may implement a vendor-hosted gate. Broader DocuSign CLM and workflow products also support approval processes. Those vendor surfaces do not automatically become Flowgrammer Document Approval DecisionEvidence. The Planner phrase DocuSign approval workflow stays in the FAQ. It is not the H1 of this page.

Who this is for

Use this when documents already go out through DocuSign and the missing piece is a verified Connect listener. You need a named sender, one document family, and a place to keep SignatureEvidence. Confirm Connect is enabled and HMAC keys exist in the Connect Keys UI before you promise a listener to a team.

You do not need this page if you are still choosing a first workflow. Start with Document Processing Automation. You also do not need it if Dropbox holds an internal approval file. That job stays on the published Dropbox document approval workflow.

The download includes:

  • Exact raw-body HMAC-SHA256 to Base64 vectors
  • Multi-key X-Docusign-Signature-N rotation
  • Missing, incorrect, truncated, CRLF, and re-serialized JSON failures
  • Fast ACK with queued work
  • SX01 through SX12 plus SX-DS-01 through SX-DS-04
  • A routing-order checklist and a forbidden-downstream sheet

Canadian Keyword Planner reports DocuSign workflow automation as 10-100. Brand search for DocuSign is navigational and does not prove workflow demand. DocuSign approval workflow is also 10-100 and stays in the FAQ.

What this adapter owns

The hub already defined send, remind, void, decline, complete, and download. It already named SignatureEvidence. It already blocked payment, bank-detail change, final accounting, auto-renew, and auto-terminate.

This page adds the DocuSign surfaces:

  • envelopeId as signature_request_id
  • Connect event identity as event_id
  • HMAC on the exact raw POST body
  • One header per configured secret key
  • JSON SIM as the preferred Connect format
  • routingOrder and change_routing_order
  • listAuditEvents as an evidence pull, not a certificate

Do not clone the hub and swap the product name. If a field is shared, keep the hub name. If a field is DocuSign-only, say so.

Connect HMAC

Official Connect HMAC and validate pages, accessed 9 September 2026, describe this check:

  1. Keep the HTTP body as received. Do not parse it and dump it again.
  2. Strip surrounding quotes from the Connect secret.
  3. Compute HMAC-SHA256 over those exact bytes, including line endings.
  4. Base64-encode the digest.
  5. Compare it to each X-Docusign-Signature-N or X-DocuSign-Signature-N header.
  6. Accept if any configured key matches.

A one-byte change fails. Switching LF to CRLF fails. Pretty-printed JSON fails. A missing header fails. User-Agent docusign is a supporting signal. It is not enough by itself.

Those Connect Help pages rendered as a JavaScript shell in this draft fetch. The HMAC rule is the official algorithm, not a tenant screenshot. Confirm Connect enablement and the Include HMAC Signature checkbox in the account you actually use.

HMAC keys are created in the Connect Keys UI. Official setup docs say the API can set includeHMAC true and cannot create the keys. The secret is shown once. Do not put a production secret in this test pack.

Rotating keys

Docs allow more than one Connect secret. Each key gets its own Signature-N header. During rotation, Signature-1 can fail while Signature-2 matches. Accept the first matching configured key. Do not require every header to pass.

The test pack case SX-DS-02 uses two fiction secrets. Signature-1 is wrong. Signature-2 is the matching KEY_B digest. The listener writes once.

ACK, then queue

Official implement guidance, accessed 9 September 2026, says plan to respond within about five seconds and queue work so downtime does not drop messages. ACK is not the SignatureEvidence write. Download the completed PDF after the ACK. Heavy work in the request thread is how listeners miss the window.

Require Acknowledgement changes how failures show in the Connect Dashboard. It does not give exactly-once delivery. Design for duplicates. The same event identity is ignored. downstream_write_count stays 0 or 1.

Admin retry APIs can republish Connect info for an envelope when Connect is enabled. Do not invent an automatic retry schedule. The Dashboard Retry Count aggregates failures. Prefer JSON SIM over legacy Aggregate when you can choose.

Connect configuration is account-level, envelope-level eventNotification, or Recipient Connect. Subscribe narrowly. Official security docs say OAuth is available for Connect. Basic Auth is for Account and Recipient Connect and cannot be combined with OAuth for Connect. Confirm the current pairing in your tenant.

routingOrder is not approval

When you create an envelope from a template, leave routingOrder out of the API role or match the template. If the API order differs, set change_routing_order=true. Official developer-blog guidance, fetched 9 September 2026, says a mismatch without that flag can drop tabs and send the signer into free-form signing.

If routing is disabled in the web console, roles share order 1 and run in parallel. Official signing-order guidance can include a manager who approves before another recipient signs. Official field types include Approve and Decline actions that can record a vendor-hosted gate. Broader CLM workflows can review and approve contracts. None of those vendor surfaces automatically become Document Approval DecisionEvidence. This URL is not a DocuSign approval workflow page.

SX-DS-01 records routing_order_exception when the flag is omitted. SX-DS-04 records parallel when every role is order 1. SX12 checks that the observed order matches the stored routing_policy.

Scheduled sending and delayed routing are plan-gated. Official developer-blog categories, accessed 9 September 2026: scheduled sending on Standard and above; delayed routing on Enterprise Pro or the Advanced Workflow add-on for Business Pro. Demo accounts can try both. Confirm the screens you see. No seat prices appear here.

API hourly and burst limits exist. Do not invent a numeric quota.

listAuditEvents

GET /v2.1/accounts/{accountId}/envelopes/{envelopeId}/audit_events returns name and value history arrays. Prefer Connect for status changes. Use the audit call when you need history. That pull is not a Flowgrammer legal certification and not DecisionEvidence.

Forbidden downstream

These writes stay blocked after a verified complete:

  • payment
  • supplier bank-detail change
  • final accounting post
  • auto-renew
  • auto-terminate
  • legal interpretation as an automation outcome
  • claiming jurisdiction-wide legal validity

Allowed after verified HMAC, completed status, artifact_ready, and a named human gate: notify, and file the completed artifacts once. If money is the real job, use invoice processing automation. If renewal is the real job, use the contract tracker. If the file still needs extraction, use intelligent document processing.

Worked example

Fictional Cedar & Quay Fabrication Ltd sends supplier agreement DOC-CQ-SIGN-014 version 1.0. Jordan Hale is the named sender. Morgan Reid signs as Supplier_Signer. Avery Chen holds the human gate for any post-sign notify or file action.

Jordan captures envelopeId env:FICTION-CQ-SIGN-014, template tmpl:cq-sign-014 version v1.0, and a document bind before send. The listener stores UTC receive time and verifies HMAC on the raw body before it parses the event.

A verified completion event evt:cq-sign-1401 writes one SignatureEvidence row. artifact_ready is yes. downstream_action is notify. downstream_write_count is 1. Nothing pays a supplier and nothing renews the agreement.

The paired pack walks that envelope through SX01–SX12 and the four DocuSign extras. Samples stay fictional. There is no live tenant in the pack.

The DocuSign workflow

  1. Name the document family, sender, signer roles, and routing policy.
  2. Confirm Connect, HMAC keys, and Include HMAC Signature in the tenant.
  3. If an org decision is required before send, open the Document Approval Workflow.
  4. Capture template id, template version, and document bind. Refuse send on a stale version.
  5. Send. Record envelopeId.
  6. ACK the Connect notification quickly. Queue verification, storage, and download.
  7. Verify HMAC on the exact raw body. Accept any matching Signature-N key.
  8. Ignore a replayed event identity.
  9. Wait until artifacts are downloadable before filing the final PDF.
  10. After verified complete plus artifact_ready, a named person may notify or file once.

What can run automatically, and what cannot

Event Automatic Review Human only
ACK a Connect notification Yes, quickly Slow handlers Treating ACK as a completed write
Verify HMAC on the raw body Yes, constant-time compare Failed or missing Signature-N Turning a failed check into a complete
Accept a later rotating key Yes, if configured Key inventory Using a fiction pack secret in production
Ignore a duplicate event id Yes First-write dispute Second downstream write
Queue document download Yes, after ACK Missing artifact Filing the PDF in the request thread
routingOrder mismatch Flag routing_order_exception Whether tabs were lost Calling free-form signing an approval
Post-sign notify or file After verified complete plus artifact_ready plus named gate Destination path Payment, bank change, accounting, renew, terminate
Org approval before send Open the approval path Vendor routing, Approve/Decline, or CLM labels Treating those vendor surfaces as DecisionEvidence

Human decisions

A named sender confirms the bound document and template version before send. A named person confirms Connect and HMAC settings before those surfaces are promised. A named person reviews failed HMAC, missing headers, unauthorized sender, stale template, decline, void, expiry, routing_order_exception, and a missing downloadable file. A named person decides any post-sign notify or file. Automation may ACK and queue. It may not invent legal validity or org approval.

Failure paths

  • Missing envelopeId or event identity. Stay in sent. Write count 0.
  • Missing or incorrect X-Docusign-Signature-N. hmac_invalid. Alert. Write count 0.
  • HMAC computed after parse-and-dump, or after an LF to CRLF change. Reject.
  • No matching rotating key. Reject.
  • Listener work that is not queued. Risk missing the documented ACK window.
  • Duplicate event identity. Keep the first downstream_ref.
  • Decline stored as a signed PDF. Status declined.
  • Void after a partial sign treated as complete. Status voided.
  • Event cites template v0.9 after send on v1.0. stale_template_version.
  • Completed before artifacts are ready. waiting_for_downloadable.
  • Sender not in the named matrix. unauthorized_sender.
  • API routingOrder differs from the template and change_routing_order is omitted. routing_order_exception.
  • Listener tries to pay or change bank details. Policy block.
  • Listener tries to auto-renew or auto-terminate. Policy block.
  • listAuditEvents, recipient signing order, Approve/Decline actions, or a CLM workflow treated as Document Approval. Open the approval parent instead.

Test cases

The pack uses fictional Cedar & Quay request ids. Expected control outcomes:

Case Input Wrong outcome Expected control
SX01 verified complete Raw-body HMAC pass, artifact ready Payment or renew write One row; notify; write count 1
SX02 duplicate event Same event id replayed Second file write Ignore; downstream_ref unchanged
SX03 failed verification Bad or missing Signature-N Event log write Alert; write count 0
SX04 decline Signer declines Signed PDF filed Status declined
SX05 void after partial Sender voids Silent complete Status voided
SX06 stale template Version v0.9 after v1.0 bind Send proceeds Exception or send blocked
SX07 completed before downloadable Complete event, artifact_ready no Final PDF filed Wait
SX08 unauthorized sender Riley sends Event log write Exception
SX09 auto-pay Complete tries to pay Payment write Blocked
SX10 auto-renew Complete tries to renew Contract update Blocked
SX11 approval before send Org decision still open Routing treated as SoR Link Document Approval
SX12 routing mismatch Policy sequential, observed parallel Surprise free-form Exception
SX-DS-01 change_routing_order omitted Free-form treated as approved routing_order_exception
SX-DS-02 Signature-1 fails, Signature-2 matches Valid rotation rejected Accept
SX-DS-03 Truncated body, CRLF, or re-serialized JSON Verify anyway Reject
SX-DS-04 All roles order 1 Called sequential approval Parallel routing_policy

What to measure

Record envelopes sent, share of Connect notifications verified before write, rotating-key accepts, duplicate events suppressed, ACK times over the documented window, declines and voids that did not file a signed PDF, waits for downloadable artifacts, routing_order_exception count, and completes that have a notify or file ref. Keep those as definitions. Do not invent a benchmark, accuracy rate, or ROI figure.

There is no live production Connect metric here, and no Flowgrammer customer signing case.

How to use the test pack

Download the DocuSign Connect Webhook Test Pack. It is an original fixture pack, not a Marketplace listing and not a hosted listener.

  1. Read README.md, then markdown/setup.md.
  2. Walk csv/hmac-vectors.csv against the raw-body fixtures.
  3. Confirm HV01 passes on the LF body and HV06 fails when that digest is compared to a CRLF body the harness derives from the same LF fixture.
  4. Confirm SX-DS-02 accepts Signature-2 after Signature-1 fails.
  5. Walk SX01 through SX12, then the four DocuSign extras.
  6. Keep markdown/forbidden-downstream.md next to any post-sign handoff.

The useful rules also sit on this page so the download is not the only answer.

Realistic limitations

  • This page designs DocuSign signing control. It does not certify legal validity in any jurisdiction.
  • Connect, HMAC keys, scheduled sending, and delayed routing can be plan-gated or admin-gated. Confirm the current official tables in your tenant.
  • Some Connect Help pages returned a JavaScript shell during this draft fetch. Recheck those screens at publish time.
  • JSON SIM field names can vary by Connect version. Map the event identity you actually receive.
  • Exact automatic retry intervals are not published here.
  • This system does not approve a document for the organization, extract fields, pay anyone, or change supplier bank details.
  • This guide does not rank vendors and is not a pricing page.
  • The published Dropbox Sign E-Signature Automation and Adobe Acrobat Sign Automation adapters are live. Use DocuSign vs Adobe Sign when the missing job is a written vendor choice. The published PandaDoc E-Signature Automation adapter is live.
  • This page is operational guidance, not legal advice and not a compliance certification.

Next step

Download the DocuSign Connect Webhook Test Pack for raw-body HMAC vectors and the sixteen cases.

Keep the published E-Signature Automation hub nearby for the shared model. Keep the Document Approval Status and Role Matrix nearby when an org decision is required before send.

If Connect enablement, HMAC keys, or the event log are still unclear, start with an AI Success Audit. If those pieces are already named, book a fit call to scope an AI Automation Systems build.

Sources

Frequently asked questions

What is DocuSign workflow automation on this page?

It is a named send, Connect HMAC check, ACK-then-queue path, routingOrder honesty, and a SignatureEvidence write after a verified event. It is not a generic document-processing pillar.

Is DocuSign approval workflow the same as Document Approval?

No. This page covers the eSignature Connect adapter. Recipient signing order and Approve/Decline actions may implement a vendor-hosted gate. Broader DocuSign CLM and workflow products also support approval processes. Those vendor surfaces do not automatically become Flowgrammer Document Approval DecisionEvidence. Document Approval is an org decision with a decision log. Use the published [Document Approval Workflow](/insights/document-approval-workflow) when that job is the one you need. The Planner phrase `DocuSign approval workflow` is 10-100 and stays in this FAQ. It is not the page title.

How do you validate a Connect HMAC signature?

Use the exact raw POST body, HMAC-SHA256, Base64, and every `X-Docusign-Signature-N` header. Strip quotes from the secret. Any matching key is enough. Do not verify a parsed copy of the JSON.

What if Signature-1 fails during key rotation?

Check the later headers. Official docs treat any matching configured key as valid. SX-DS-02 is that case.

Why can line endings break verification?

The digest covers the bytes as received. LF and CRLF are different bodies. The test harness derives a CRLF body from the LF fixture so that failure is visible without storing a second raw fixture.

How fast should the listener ACK?

Official implement guidance says plan for about five seconds and queue the rest. ACK is not a completed SignatureEvidence write.

Does listAuditEvents prove legal validity?

No. It returns envelope history. Counsel and vendor docs cover validity. This page automates process controls only.

Does envelope completion renew a contract or pay a supplier?

No. Those writes stay blocked. Use the [contract tracker](/insights/contract-tracker) or [invoice processing automation](/insights/invoice-processing-automation).

Do brand search volumes prove automation demand?

No. Brand DocuSign volume is navigational. The workflow phrase used here is 10-100.