Build a Governed Agreement Workflow with Docusign and Kong Konnect

Key takeaways

• Docusign Workflow Builder manages the customer-facing process, while Kong Konnect secures and routes requests to backend systems. 

• A Docusign Data IO extension app gives the workflow actions for retrieving and updating external data. 

• Mocking the API first helps you test the connection and response format before building the backend. 

• You can reuse this approach for onboarding, approvals, account updates, data synchronization, and other agreement workflows. 

A customer account update may seem simple: change an address, correct a name, or update a beneficiary. But behind the scenes, the request may need identity checks, business-rule validation, manual approval, and updates across several systems.

When these steps depend on email, manual data entry, and disconnected tools, even a routine update can take too long and be difficult to track.

In this guide, you will build a self-service account update workflow that connects Docusign to a backend system through Kong Konnect. You will:

1. Expose an API that Docusign can reach.

2. Test the integration with mocked responses. 

3. Secure the API with OAuth 2.0 and gateway policies.

4. Replace the mocked responses with a Node.js service backed by Amazon DynamoDB.

5. Build the complete customer workflow in Docusign Workflow Builder. 

The accompanying GitHub repository opens in a new tab includes the source code, configuration files, and provisioning instructions.

This guide builds on the architecture described in Automating Agreement Workflows with Kong Konnect API Gateway and Docusign for Developers opens in a new tab to show you how to implement it. 

What you will build

The implementation uses three primary components:

A Docusign Data IO extension app connects Docusign workflows to an external data source. In Docusign terminology, an extension app defines actions that Workflow Builder can invoke; for example, retrieving an account record or submitting updated customer information. 

Docusign Workflow Builder (formerly Maestro) composes those actions into an end-to-end business process. It controls how information is collected, passed between steps, written to external systems, and presented back to the customer.

Kong Konnect opens in a new tab manages and protects the APIs between Docusign and the backend application. It provides the gateway, identity integration, routing, and policy-enforcement layer without requiring those concerns to be implemented separately in every backend service. 

For this example, the backend is a Node.js application running in Amazon Elastic Kubernetes Service, or Amazon EKS, with Amazon DynamoDB serving as the system of record.

The implementation follows four stages:

• Reach: Make a contract-ready API available to Docusign.

• Secure: Require authenticated access before traffic reaches the backend.

• Execute: Replace mocked responses with real application logic.

• Orchestrate: Assemble the API actions into a complete Docusign workflow.

Each stage produces a working checkpoint. This makes it easier to isolate connection, authentication, routing, and application errors instead of debugging the entire system at once.

Before you start

You will need: 

• A Docusign developer account with access to the Developer Console and Workflow Builder

• Access to Kong Konnect opens in a new tab (free trial available)

• An AWS account with permission to provision EKS, load balancers, Route 53 records, and related resources

• Working knowledge of Kubernetes and kubectl

• Node.js installed locally

• A local clone of the accompanying GitHub repository opens in a new tab

The repository is organized by implementation stage so you can follow the configuration and deployment steps alongside this guide.

Reach: expose an API that Docusign can call 

The first goal is to establish a reliable route between Docusign and an API that responds in the format that Docusign expects.

To reach this checkpoint, you will:

1. Create the AWS infrastructure that runs the gateway and backend services.

2. Deploy a Kong Konnect Data Plane into the Kubernetes cluster.

3. Expose the gateway through a secure public endpoint.

4. Configure mocked Data IO responses.

5. Register and test the extension app in the Docusign Developer Console.

Build the foundation: AWS and Kong runtime

Start by provisioning an Amazon EKS cluster. The cluster will eventually run both the Kong Gateway Data Plane and the Node.js backend service.

Configure the EKS Pod Identity add-on so workloads in the cluster can access permitted AWS services without storing long-lived AWS credentials in application configuration. This becomes important when the backend begins reading and writing data in DynamoDB.

Next, install the AWS Load Balancer Controller. It watches Kubernetes resources and provisions the AWS load-balancing infrastructure needed to receive traffic from outside the cluster.

Create or configure the following supporting resources:

• A public domain or subdomain in Amazon Route 53

• A TLS certificate for that domain in AWS Certificate Manager

• The DNS validation record required to validate the certificate

• A Network Load Balancer that forwards public HTTPS traffic to the Kong Data Plane

The resulting request path should look like this:

Docusign → public HTTPS endpoint → Network Load Balancer → Kong Data Plane

Deploy the Kong Data Plane into EKS and connect it to a Kong Konnect Control Plane. The Control Plane stores and distributes gateway configuration, while the Data Plane receives live API traffic inside your AWS environment.

Once the Data Plane is connected, create a Gateway Service and Route for the extension app. The route should be available through the public hostname you configured, such as:

https://api.example.com/data-io/

At this point, the endpoint is publicly reachable, but it does not yet have a working application behind it.

The repository includes the Kubernetes manifests and AWS deployment instructions opens in a new tab for provisioning the EKS cluster, configuring certificates, and deploying Kong.

Validate the Data IO interaction with mocked responses 

Before building the Node.js service, configure Kong to return sample responses that match the format Docusign expects, as defined by the extension contract.

This is where the Kong Mocking plugin is useful.

The plugin reads an OpenAPI specification (a machine-readable description of an API’s routes, inputs, and outputs) and generates example responses without forwarding the request to a real backend. In this implementation, the OpenAPI file defines the Data IO endpoints required by the Data IO extension contract, along with representative response payloads.

The flow temporarily becomes:

Docusign → Kong Gateway → response generated from the OpenAPI specification

This gives you an early way to confirm three things:

• Docusign can reach the public gateway.

• The configured routes match the extension app actions.

• The returned data has the structure Docusign expects.

It also separates integration problems from application problems. If the mocked version works but the live backend later fails, you know the issue is likely in routing or application logic rather than the initial Docusign configuration.

Use the OpenAPI specification provided in the repository opens in a new tab to create the Gateway Service, configure its routes, and enable the Mocking plugin.

Register the extension app

Now register the Data IO extension app in the Docusign Developer Console.

An extension app is the Docusign configuration that describes an external integration and the actions it makes available to other Docusign capabilities. For this workflow, those actions will eventually retrieve an account record and submit updated account information.

During registration:

1. Create a new Data IO extension app.

2. Add the required action definitions.

3. Enter the public Kong Gateway URL as the app’s API endpoint.

4. Configure the initial authentication values required by the sample.

5. Run the Developer Console connection test.

Follow the repository’s extension app development configuration opens in a new tab to enter the gateway URL, define the actions, and run the initial connection test. 

The test should send requests from Docusign to Kong and receive the mocked responses generated from the OpenAPI definition. A successful result confirms that the gateway is reachable and that the extension app can interpret the responses.

Secure: enforce identity and policy at the gateway

The extension app can now reach the API, but the current configuration is not ready for production use. The token behavior and API responses are still mocked.

The next step is to require a valid access token before Kong allows a request to reach any protected route.

For this implementation, we use Kong Identity as the OAuth 2.0 authorization server and the Kong OpenID Connect plugin opens in a new tab to validate tokens. This keeps authentication and authorization enforcement at the gateway rather than embedding it directly in the Node.js application.

Docusign extension apps can also use other supported OAuth 2.0 and OpenID Connect configurations. See the Docusign extension app authorization documentation for supported options.

Configure Kong Identity and OAuth 2.0

In Kong Konnect, configure opens in a new tab an OAuth 2.0 authorization server in Kong Identity opens in a new tab. Then create an OAuth client representing the Docusign extension app.  

Record the following values:

• Client ID

• Client secret

• Token endpoint

• Required scopes

• Issuer and audience values, when applicable

Docusign will use the client credentials to request an access token. It will then include that token when it calls the Data IO actions.

Configure the Kong OpenID Connect plugin on the protected gateway routes. For each request, the plugin should:

1. Read the bearer token from the authorization header.

2. Validate the token’s signature and issuer.

3. Confirm that the token is active and intended for the protected API.

4. Check any required scopes or claims.

5. Reject invalid requests before they reach the upstream service.

Valid requests continue to the mocked endpoints from the Reach stage. This allows you to verify authentication independently before introducing the live application.

Update the extension app authentication settings

Return to the Docusign Developer Console and update the extension app with the Kong Identity configuration.

Enter the token endpoint, client ID, client secret, and required scopes. Confirm that the configured API endpoint still points to the protected Kong Gateway route.

Run the connection test again.

This time, the expected sequence is:

1. Docusign sends the client credentials to the Kong Identity token endpoint.

2. Kong Identity returns an access token.

3. Docusign calls the Data IO endpoint with the token.

4. Kong validates the token.

5. Kong returns the mocked Data IO response.

If the connection test fails, check the failure stage before changing multiple settings at once.

If token acquisition fails:

• Confirm that the token endpoint is correct and publicly reachable.

• Check the client ID and client secret for copied spaces or expired credentials.

• Confirm that the scopes in the Developer Console match the scopes configured for the client.

If token acquisition succeeds but the API request is rejected:

• Check the OIDC plugin’s issuer and audience configuration.

• Confirm that the access token contains the expected scopes or claims.

• Verify that the plugin is applied to the correct Kong Service or Route.

• Review the Kong gateway logs for the authorization failure.

If authentication succeeds but the extension test reports a response error:

• Confirm that the Mocking plugin is still enabled.

• Compare the returned response with the OpenAPI example.

Check that the response’s field names and data types match the extension action definition.

Execute: connect the workflow to a real system of record

Once the gateway is reachable and authentication works, replace the mocked responses with a real backend service.

In this example, the service is a Node.js application backed by Amazon DynamoDB. The application retrieves account information and writes approved customer updates to persistent storage.

The specific backend technology is flexible. Docusign depends on the extension app’s defined inputs and outputs, not on how the application implements its business logic.

Build the Node.js service

Create a Node.js application that implements the Data IO endpoints described in the OpenAPI specification.

For the account maintenance workflow, the service needs at least two logical operations:

• Retrieve an account using information supplied by the workflow.

• Update selected account fields after the customer submits the revised information.

A request handler should:

1. Validate the incoming request.

2. Extract the account identifier and action inputs.

3. Read or update the corresponding DynamoDB record.

4. Map the application result into the response format expected by the extension action.

5. Return an appropriate success or error response.

Keep the Docusign-facing response mapping separate from the core account-update logic where possible. This makes it easier to change the backend implementation without changing the extension app’s interaction model.

export const patchRecord = async (req: IReq<PatchRecordBody>, res: IRes): Promise<IRes> => {
  const {
    body: {
      data,
      typeName,
      recordId
    },
  } = req;
  try {
    if (!data || !typeName || !recordId) {
      return res.status(400).json(generateErrorResponse(ErrorCode.BAD_REQUEST, 'data, typeName or recordId missing in request'));
    }
    const resolvedTypeName = resolveTypeName(typeName);
    if (!resolvedTypeName) {
      return res.status(400).json(generateErrorResponse(ErrorCode.BAD_REQUEST, `Unsupported typeName: ${typeName}`));
    }
    normalizeDateOnlyProperties(data, resolvedTypeName);
    formatISO8061DateProperties(data, resolvedTypeName);

    const dynamoTableName = getDynamoDBTableName(resolvedTypeName);
    const keyName = getDynamoDBKeyName(resolvedTypeName);
    if (!dynamoTableName || !keyName) {
      return res.status(500).json(generateErrorResponse(ErrorCode.INTERNAL_ERROR, `Missing DynamoDB table mapping for typeName: ${resolvedTypeName}`));
    }

    const db = new DynamoDB(dynamoTableName, keyName);
    await db.updateItem(recordId, data as Record<string, any>);
    return res.json({ success: true });
  } catch (err: unknown) {
    const errorMessage = getErrorMessage(err);
    console.log(`Encountered an error patching data: ${errorMessage}`);
    return res.status(500).json(generateErrorResponse(ErrorCode.INTERNAL_ERROR, errorMessage));
  }
};

Deploy the service to EKS

Use the repository’s backend deployment instructions opens in a new tab to package the application as a container and deploy it to the existing EKS cluste 

Create a Kubernetes Service so the Kong Data Plane can reach the application over the cluster’s internal network. The backend service does not need to be directly exposed to the public internet; Kong remains the public entry point.

The request path now becomes:

Docusign → Kong Gateway → Node.js service → DynamoDB

Ensure that the application’s Kubernetes service account has permission to perform only the required DynamoDB actions against the appropriate table.

Replace the mocked routes with the live service

After the backend is running, update the Kong Gateway Service so requests are forwarded to the Node.js application.

Remove the Mocking plugin from the relevant Service or Route. This step is easy to overlook: while the plugin remains enabled, Kong can continue returning generated responses instead of forwarding requests to the backend.

Run the Developer Console connection test again.

The same extension actions should now return live data from DynamoDB rather than examples from the OpenAPI file. Because the public endpoint and action definitions have not changed, this checkpoint verifies that the implementation behind the integration can be replaced without changing the Docusign-facing interface.

Orchestrate: build the complete workflow

The extension app now provides authenticated actions backed by a live system of record. The final step is to compose those actions into a customer-facing process using Docusign Workflow Builder. 

Define the account update flow 

Follow the repository’s step-by-step Workflow Builder configuration opens in a new tab to create a workflow with the following sequence 

1. Collect the account identifier: The customer enters identifying information through a web form.

2. Retrieve the account: Workflow Builder passes the form input to the extension app’s lookup action.

3. Prefill the update form: The extension app returns the current account information, which Workflow Builder maps into a second web form.

4. Collect the requested changes: The customer reviews the existing information and submits any updates.

5. Write the updates to the system of record: Workflow Builder passes the revised values to the extension app’s update action, which writes them to DynamoDB.

6. Confirm completion: The workflow displays a success message or routes an exception for additional review.

This produces a single agreement-driven process in which customer input, API execution, and system updates are coordinated through the workflow.

Why this architecture is reusable

The account maintenance example is only one application of the pattern.

The same architecture can support workflows such as:

• Customer or employee onboarding

• Supplier information updates

• Approval routing

• Policy acknowledgements

• Renewal and obligation management

• Data synchronization between agreement processes and internal systems

Each layer has a distinct responsibility:

This separation makes the system easier to evolve.

The workflow can change without requiring a new authentication implementation. Gateway policies can change without modifying the Node.js application. The backend can be replaced or expanded as long as it continues supporting the interaction expected by the extension contract.

FAQ

What is a Docusign extension app?

An extension app connects an external capability or data source to the Docusign platform. A Data IO extension app defines actions that Docusign workflows can invoke, such as retrieving a record or submitting an update.

Why should I mock the API before building the backend?

Mocking confirms that Docusign can reach the gateway and understand its responses before application logic is introduced. It gives you a known-good integration checkpoint and reduces the number of possible causes when troubleshooting later.

Do I need to finish the infrastructure before registering the extension app?

You need a publicly reachable endpoint before the Developer Console can test the connection. The backend application does not need to be complete, because Kong can initially return mocked responses.

Can I use another cloud provider?

Yes. AWS and EKS are used in this implementation, but the broader pattern is not limited to AWS. You need a runtime that can host the gateway and backend service and expose a secure endpoint to Docusign.

Can the workflow support multiple account update types?

Yes. You can add fields, conditional branches, approval steps, or additional extension actions while retaining the same overall architecture.

Is this pattern limited to account maintenance?

No. It applies whenever a Docusign workflow needs to securely retrieve data from or submit data to an external system.

Next steps

Use the accompanying GitHub repository opens in a new tab to deploy the complete example. From there, consider extending the implementation in the following ways: 

• Add extension actions for more data operations.

• Apply rate limiting, logging, or request-transformation policies in Kong.

• Add approval routing for high-risk or exceptional changes.

• Connect the extension app to an existing enterprise system of record.

• Add monitoring for authentication failures, gateway errors, and backend latency.

Resources

• Get a free Docusign developer account

• Automating Agreement Workflows with Kong Konnect and Docusign for Developers opens in a new tab

• Docusign Extension Apps 101

• Data IO Extension Contracts reference

• Docusign Workflow Builder API documentation

• Kong Konnect documentation opens in a new tab

• Kong Identity documentation opens in a new tab

• GitHub repository: extension-app-kong opens in a new tab