Skip to navigation
Platform 101Webhooks

Legacy event message formats

View as Markdown

This page describes the JSON aggregate and XML aggregate message formats for Docusign Connect.

By default, Docusign Connect sends its notifications using the JSON SIM event model. This format combines the advantages of previous formats and is recommended for all apps, but switching to use it will require code changes to your current Connect setup.

See JSON SIM event model for details on the format, a list of supported events, and information on how to enable it for your account.

Aggregate event models

Note: This section describes the behavior of the older Connect event model, which is no longer recommended for new apps. When possible, use the JSON SIM event model instead.

The JSON and XML Aggregate message modes work by grouping event messages for periodic sending.

In these modes, Docusign Connect and the eventNotification (envelope-level Connect) feature a group of messages sent as an aggregate status message to the customer’s listener. In addition, each message within an aggregate message reflects the envelope’s status when the message was sent, not when the event occurred. As a result of this algorithm, it may seem that customers sometimes may not receive a certain message, as Connect has already aggregated the message into a later status. The benefit is that your listener always gets the latest status, and aggregation decreases the message load drastically.

In the JSON and XML aggregate message modes:

  • Messages reflect the envelope status when the message is sent to the listener.
  • Messages show the current envelope status when the message is sent.
  • Messages are sent in the order that the events occurred, except for notification failures. When a failed notification is retried, it’s possible that some events appear to be lost, especially if a later message is sent successfully as a result of aggregation.
  • You can order your messages using the TimeGenerated element.

If message delivery for a given envelope fails, retries will be attempted using exponential back-off. The retry attempts will be made in the following sequence:

  • 5 minutes later
  • 10 minutes later
  • 20 minutes later
  • 40 minutes later
  • 1 hour later
  • 2 hours later
  • 1 day later
  • Once per day for a 15 day span.

Note: If message delivery for envelope A fails, Connect will attempt message delivery for envelope B.

Data format: Legacy vs. REST v2.1 format

The Docusign Connect webhook service offers flexible payloads to suit your needs. Regardless of which data format you pick, each will allow a fine-controlled selection of data to pass back with each envelope event, including documents, tab data, recipient information, and more.

The Legacy format is an older XML-based message format. It can be configured to be a SOAP request. It has the same object model as the eSignature SOAP API. Key reasons to use the Legacy format:

  • Prefer XML
  • Prefer to standardize parsers and object models against the SOAP API
  • Want to use the SOAP interface
  • Want to ensure payload never changes over the course of your integration

The REST v2.1 format is a newer JSON format based on the eSignature REST v2.1 object model. It is the only format available for SIM and is also available if you have enabled Aggregate mode. If you’re using the eSignature REST v2.1 API, the objects will be very familiar. Key reasons to use the REST v2.1 format:

  • Prefer JSON
  • Prefer to standardize parsers and object models against the eSignature REST API
  • Want to take advantage of features not available in the SOAP API, such as ID Verification or two-factor authentication
  • Payload will never contain breaking changes (such as removal/modification of a property), but may gradually include more data as new features/capabilities are added to Docusign.

Next steps