Automate your agreement flows using data verification results with Docusign Connect events

The Docusign Connect webhook service lets your apps listen for updates and respond to the events you care about by automating your next steps and actions. Connect has grown from supporting only eSignature to include events around recipients, templates, Maestro, and now, data verification extension apps with the new extension-executed event.

Extension apps let you bring your own custom functionality into Docusign by calling endpoints of other platforms (such as reading and writing data to your system of record) and build an end-to-end agreement workflow that supports your existing processes for data exchange and verification, integration with your systems, and storage. Docusign Maestro enables you to easily set up sequences of steps for your flows that can extend beyond getting an agreement through eSignature, including branching logic and invoking extension apps that integrate your systems with external data sources. Using Connect events like extension-executed (and more extension app Connect events that are planned to be supported in the future), you can begin to chain together the steps in your agreements, both inside and outside of Docusign. 

Learn about our new extension-executed event

The new event is extension-executed, which should be used by data verification extensions for eSignature apps. It’s sent after your recipient has completed their data verification process and contains information about the verification result and metadata. 

Here’s what an example extension-executed payload looks like:

{
  "event": "extension-executed",
  "apiVersion": "v2.1",
  "retryCount": 0,
  "configurationId": 20027675,
  "generatedDateTime": "2024-10-07T23:14:30.1376971Z",
  "data": {
    "accountId": "4ae4d0ac-xxxx-xxxx-xxxx-dc537ea7bd9a",
    "userId": "13b7d93d-xxxx-xxxx-xxxx-3f631c675ac4",
    "extensionPoint": "eSignature",
    "recipientId": "00000000-0000-0000-0000-000000000004",
    "entityType": "Envelope",
    "entityId": "00000000-0000-0000-0000-000000000005",
    "extension": {
      "type": "DataVerification",
      "instanceGroupId": "mockInstanceGroup",
      "appName": "openweathermap-6e38fc63-xxxx-xxxx-xxxx-eba159e402ec-update",
      "appId": "0c035c45-xxxx-xxxx-xxxx-ec64f8671f44",
      "actionContract": "Contracts.Actions.Verify.Version.01.Something",
      "attemptTime": "2024-10-07T23:14:26.240Z",
      "configurationPolicy": "Must Verify to Sign",
      "data": {
        "verified": true,
        "maxAttemptsPolicy": 10
      },
      "attemptDurationMs": 499,
      "attemptNumber": 2
    }
  }
}

You can use this information to kick off new steps in your process, reduce document errors, avoid not-in-good-order (NIGO) forms, and detect signers who become stuck in the signing process as a result of failing to verify their identity for agreements where that is required. This can save you money on post-signature processing costs: envelopes that are completed incorrectly or contain bad information may be considered NIGO and are invalid. The impact of inaccurate bank account data, for example, may be quite expensive and painful!

Docusign Connect events such as extension-executed give you a way to access extension events that is more scalable and easier than using the Docusign web app or making API calls to check on your envelope’s status. As with all new Connect events, extension-executed is only supported in our JSON SIM (Connect 2.0) event model.

Best practices for using the extension-executed Connect event

• Map your data verification implementation to your business process requirements. Discuss and review your end-to-end process with all business stakeholders to determine which kinds of data verification are required.

• Don’t process duplicate events. Because multiple verification attempts can be made for an individual field group, you only need to process the latest one. Inspect the instanceGroupId property of each event as it is delivered; if it matches an event that you’ve already received, only process the latest one. Generally, try to wait 30–60 seconds before processing an event to ensure that you’re always processing the latest one.

• Handle critical events as a priority! A verification failure for a bank account number may be more important than for an email address or phone number, for example, and your implementation may want to be able to differentiate and prioritize among them.

• Consider implementing rate and throttle limits to protect against excessive loads.

• Process your events efficiently by aggregating them by recipientId and entityId.

Example scenario

As an example of when extension-executed can make your life easier, let’s explore the following scenario:

As a financial advisor, you need to quickly and efficiently respond to clients and anticipate updates in your agreements while ensuring compliance and minimizing the amount of time you spend on routine tasks. Implementing extension-executed can make it easier to scale handling account updates and react to and prevent NIGO agreements, as shown in the following flow:

1. As a financial advisor, you receive a request from a client to update the ownership of an account, such as changing an individual owner to an entity or trust.

2. You identify which agreements need to be updated and obtain the latest custodial agreements. (Forms can be obtained from integrations with forms providers.)

3. You create agreements with data verification fields (primary and secondary email, phone, address, bank accounts, and SSN) and send them for the client to review and sign.

4. The client reviews and signs your new agreements. This automatically triggers your extension-executed Connect event.

5. The listener receives the event and notifies you that data verification is complete, enabling you to follow your client’s progress and take additional actions. For example, based on the verification result and extension type, you can route the agreement for processing in different ways, such as having your payment operations team follow up with customers who fail bank account verification.

What’s next

This event is only the first of many extension Connect events we plan to introduce! Keep an eye out for other exciting extension app updates planned for this year, such as new extension types, extension points, and enabling you to aggregate extension connect events by session. Stay up-to-date on the latest features by checking out our roadmap on GitHub and joining the Docusign Developer Community.

Additional resources

• JSON SIM event reference

• Webhook event triggers