Docusign Connect: how its webhooks work

What Docusign Connect does

Docusign Connect is the Docusign webhook service. You publish an HTTPS endpoint, called a listener, and choose the events you want to hear about. Connect sends an HTTPS POST request to the listener after a subscribed event occurs. Your code acts on the message: it moves a deal to the next stage, or files the signed PDF against the customer record.

The listener must sit on the public internet. The URL must use HTTPS, and the server certificate must chain to a certificate authority on Microsoft's trusted list. Self-signed certificates do not work. Connect uses port 443 unless the URL names one of the nine other ports Docusign lists, from 1443 to 9443.

Without Connect, you poll Docusign for the status, and the Docusign API rules set the pace. An app may send one status request per envelope every 15 minutes, and a breach can fail the go-live review. Connect messages do not count against your API request limits. The webhook vs API guide sets out the general choice.

Connect sends events out of Docusign. A Docusign Workflow Builder workflow that another system starts uses the From an API call start method.

Account-level or per-envelope

Choose by who creates the envelope. Attach the subscription to the envelope if your application creates every envelope through the API. Configure Connect on the account if staff also send from the Docusign web app: an account-level listener suits envelopes whose lifecycle your application does not control.

The first three rows come from the Docusign listener guide, and the groups in the second row from its support article on Connect. The count comes from its configuration limits, and the last two rows from the pages on pausing and security.

Docusign documents two more levels. Recipient Connect reports on envelopes that users in your organization receive, and the other levels report on envelopes those users send. Organization-Level Connect applies one configuration across the accounts of an organization. It supports the JSON SIM format alone, and an account-level configuration overrides it where the two differ.

The events you can subscribe to

Docusign names each event after the object that changed. The JSON SIM event reference starts with envelope and recipient events, then lists events for templates, elastic templates, SMS consent, Docusign Workflow Builder, identity verification, extension apps and notary sessions.

Read the Docusign definitions before you map an event to an action. Four definitions matter most when you map events to actions:

• envelope-sent: Docusign sent the email notification to at least one recipient, or a recipient's turn came up in embedded signing.
• envelope-delivered: all recipients have opened the envelope on the Docusign signing website. The event does not signify email delivery.
• envelope-voided: the sender voided the envelope, or the envelope expired. The void reason tells you which.
• recipient-completed: the recipient finished their actions, with or without a signature.

envelope-completed means all recipients have completed the envelope. Wait for that event before you start a write-back that needs the signed document.

The event list depends on the format. Docusign marks envelope-created, envelope-corrected, recipient-reassign and others as available in the JSON SIM format alone. In SIM mode the recipient-sent message arrives before envelope-sent.

Message formats

Use JSON SIM unless a legacy consumer needs XML. SIM stands for Send Individual Messages. Connect sends one message per event, and the data describes the moment the event occurred. Docusign recommends the format for all apps, and JSON and SIM are the defaults in its configuration settings. The Docusign sample message for a sent envelope reads:

{
   "event": "envelope-sent",
   "uri": "/restapi/{apiVersion}/accounts/{accountId}/envelopes/{envelopeId}",
   "retryCount": 0,
   "configurationId": 10242474,
   "apiVersion": "v2.1",
   "generatedDateTime": "2021-05-14T23:15:56.3570000Z",
   "data": {
      "accountId": "0000000-0000-0000-0000-000000000000",
      "userId": "12345678-xxxx-xxxx-xxxx-123456789abc",
      "envelopeId": "cc6803ce-xxxx-xxxx-xxxx-3c4f50733703",
      "envelopeSummary": "rest of envelope summary"
   }
}

Each message carries the event name, a set of standard fields and a data object that varies by event. The envelope summary is optional: you request parts of it through includeData, with values such as recipients, custom_fields and tabs. Docusign warns that a summary enlarges the payload and can delay delivery.

The legacy formats are JSON aggregate, XML aggregate and XML SIM. Aggregate mode groups messages for periodic sending, and each message shows the envelope status at the time of sending, so a message can miss a short-lived state. You cannot change the data format or the delivery mode after you save a configuration, so a change of format takes a new configuration.

How to secure the listener

Docusign documents four mechanisms, and its stated best practice for production is HMAC together with OAuth.

The HMAC hash covers the entire body, line endings included, so hash the raw bytes. Docusign sends one signature header per key, up to one hundred, and one match is enough. The Connect Keys screen shows each key in full once, at creation.

With OAuth, verifying the token is your responsibility. Mutual TLS identifies the caller, and your server still has to decide whether to accept it. Docusign recommends HMAC for that access control because HMAC also checks message integrity.

What Docusign does when the listener fails

With Require Acknowledgment on, Connect waits for an HTTP 200 from the listener and records success if the 200 arrives within 100 seconds, and a failure otherwise. In its developer guidance, Docusign sets a tighter target: respond within five seconds.

Docusign lists the retry sequence: five minutes later, then 10, 20 and 40 minutes later, then one hour, two hours and one day later, then once per day for a 15-day span. Its support article shows the same sequence with an ellipsis between the two-hour and one-day steps, so allow for further attempts in that interval. Its worked example puts a failure at 3:00 PM and the retries at 3:05, 3:15 and 3:35, so each interval counts from the previous attempt.

Retries run for Organization-Level configurations, and for account-level configurations with Require Acknowledgment selected. Docusign does not state whether envelope-level notifications retry. Its sample eventNotification object sets requireAcknowledgment to true, so set it and test a failed delivery. A failing message for one envelope does not hold back the messages for another.

Docusign deactivates a configuration that keeps failing. After the configuration fails almost every time over three days, its status becomes Active - Pending Deactivation. After at least 14 days in total, the status becomes System Deactivated. Docusign emails the administrators three times, the last time to report the deactivation. New messages stop, and API access to envelopes continues.

Three places hold the failure record:

• The Connect Dashboard lists the most recent 500 event notifications, each with a retry count and an error message.
• The Logs tab keeps the 100 most recent entries for the account, provided Enable Log is on for the configuration.
• The API returns failures through ConnectEvents: listFailures, and Docusign deletes those logs after 15 days.

To republish, an administrator opens the Publish tab in the Connect area, selects the envelopes and chooses the configurations to send to. Your code can do the same through the ConnectEvents resource, with retryForEnvelope for one envelope and retryForEnvelopes for a batch.

What goes wrong in production

The listener does its work before it answers

The handler writes to the CRM, and the CRM takes two minutes. The 200 leaves after the 100-second window has closed. Connect records a failure and resends the message. Use the design Docusign documents: add the message to a nonvolatile queue, send the 200, and let worker processes clear the queue.

The same event arrives twice

A retry after a late acknowledgment causes it, and so does a manual republish. Docusign names a third source: a system that collects events through Connect and through API calls receives the same event once from each. Make the downstream write safe to repeat. For an event that occurs once per envelope, such as envelope-completed, key the write on the envelope ID and the event name. Recipient events carry a recipientId, so add it to the key. An event such as envelope-resent fires on each resend, so process each one. The idempotency keys guide shows the pattern.

An old message arrives after a new one

A retried message can arrive after newer ones. For the aggregate formats Docusign states that a notification failure breaks event order, and it names the TimeGenerated element for ordering. A JSON SIM message carries generatedDateTime and retryCount, and the JSON SIM reference defines neither field. Compare generatedDateTime before you overwrite a newer status, and test that the value survives a retry.

Valid messages fail the HMAC check

A web framework parses the JSON, and the code hashes the re-serialized text. That text differs from the bytes Docusign signed. Hash the raw request body. After a key rotation, check the header number: removing a key shifts each key below it up by one.

The listener rejects events it does not need

Each rejection counts as a failure and starts the retry sequence. Docusign asks you to return 200 and then discard the message.

Every message carries the documents

Payloads grow, and a bulk send floods the listener. Subscribe to recipient events with basic data, and request the document on the completed event alone. An administrator can pause an account-level configuration while the queue drains. Docusign skips the retries that fall inside the pause and continues at the next scheduled retry, and an event that passes its 15-day window needs a manual republish. Docusign disables a configuration that stays paused for 14 consecutive days.

Production receives nothing after go-live

Docusign keeps Connect configurations in the developer account separate from production. Create the configuration and its HMAC key in the production account before the first live envelope. The Docusign API integration guide lists the other go-live steps.

On the platforms you connect

The worker needs the ID of the record it will update, so put that ID on the envelope at creation. The Docusign example reads a sales order ID from an envelope custom field in the event message. A custom field value holds up to 100 characters.

Docusign publishes apps for each system below. Docusign eSignature for Salesforce updates Salesforce fields after signing and saves the signed documents to the record. The HubSpot app from Docusign adds Read from HubSpot, Writeback to HubSpot and Store Files in HubSpot steps to Docusign Workflow Builder. Docusign for NetSuite posts the signed documents back to the NetSuite record as a PDF. Use them where they fit your process. The patterns below are for a listener you run yourself.

HubSpot. On envelope-completed the worker moves the deal in HubSpot. The deals API takes a PATCH request to /crm/objects/2026-09/deals/{dealId}. The create example on the same page puts dealstage inside a properties object. HubSpot requires the stage's internal ID when you create a deal through the API, and you find that ID in the deal pipeline settings. HubSpot allows an app with private distribution 100 requests per 10 seconds on Free and Starter, and 190 on Professional and Enterprise, so pace the queue after a bulk send.

Salesforce. Store the envelope ID in an external ID field in Salesforce and upsert through the sObject Rows by External ID resource. If the ID matches one record, Salesforce updates it. If nothing matches, Salesforce creates a record, unless you add updateOnly to the URL. A repeated Connect message lands on the same record, and several matches return a 300 error.

NetSuite. In NetSuite, the REST upsert needs an external ID in the URL and the PUT method, as in PUT /services/rest/record/v1/customer/eid:CID002. For asynchronous requests NetSuite accepts an X-NetSuite-idempotency-key header and answers a duplicate with an error that points to the earlier job.