Set up digital signing in Salesforce

This guide walks Salesforce administrators through the one-time configuration required to enable signing documents in the Nutrient Documents for Salesforce.

The setup has two parts:

1. Outbound — Salesforce calls the DWS API (create envelopes, upload documents, cancel envelopes).
2. Inbound — DWS sends webhook events back to Salesforce (for example, envelope_completed, signer_signed).

Who should use this guide

Use this guide if you’re a Salesforce administrator or implementation owner configuring Nutrient documents signing for your organization.

Prerequisites

Before you start, ensure you have:

• The basic Nutrient Documents for Salesforce setup is complete
• Admin access to your Salesforce organization
• The Nutrient package installed in Salesforce
• Access to DWS Signer and an API key
• A dedicated Salesforce integration user for webhooks (recommended)

If your organization still needs the app-level setup, refer to the set up Nutrient Documents for Salesforce guide. If users will send documents for signing from Salesforce records, also refer to the set up document generation in Salesforce guide.

If you need the Salesforce installation link, DWS Signer dashboard access, or a DWS Signer API key, contact our Sales team.

If you already have access to the DWS Signer dashboard, follow these steps to obtain the API key:

1. Select Signer API in the upper-left corner.

   
   

2. Click the API key tab in the left navigation panel.

   
   

3. Copy the API key.

Part A — Connect Salesforce to DWS API (outbound)

Create an external credential and a named credential so Salesforce can authenticate callouts to DWS.

1. Create an external credential

1. In Setup, search for Named Credentials in quick find.

   
   

2. Open External Credentials.

3. Click New.

   
   

4. Enter the label/name, for example NutrientDWSSigning.

5. Set Authentication Protocol to Custom.

6. Save.

   
   

2. Create a named credential

1. In Setup, open Named Credentials.

2. Click New.

   
   

3. Enter the label/name and URL:

   • https://api.nutrient.io

4. Select the external credential you just created.

5. Enable:

   • Generate Authorization Header
   • Allow Formulas in HTTP Header

6. Save.

   
   

3. Store the API key and set the authorization header

1. Open the external credential from step 1.

2. In Principals, click New.

   
   

3. Create a Named Principal (parameter name example: Signing Key).

4. Add the authentication parameter:

   • Name — APIKey
   • Value — your DWS Signer API key

5. Save.

   
   

6. In Custom Headers, click New.

   
   

7. Add the header values:

   • Name — Authorization
   • Value — Bearer {!$Credential.NutrientDWSSigning.APIKey}
   • Sequence Number — 1

8. Save.

   
   

4. Grant users access to the DWS external credential

Salesforce requires explicit permission before a user can use a stored external credential.

In the previous steps, you created an external credential and stored the DWS API key in a principal named something like:

NutrientDWSSigning - Signing Key

This principal represents the DWS API key Salesforce uses when making outbound signing requests. Any Salesforce user who sends documents for signing, tests the signing connection, or runs signing-related callouts must be granted access to this external credential principal. Otherwise, the DWS API key may be configured correctly, but Salesforce will block the user from using it.

What this enables

Granting external credential principal access enables Salesforce to make authenticated outbound calls to DWS in response to a user action. For example:

User clicks Send for Signing → Nutrient Salesforce app makes a callout → Named Credential points to DWS → External Credential applies the stored DWS API key → DWS receives the request

Without this permission, the callout can fail even if the named credential and API key are correct.

Option A — Quick setup for testing

For a first-time setup or test organization, you can grant access directly on the packaged Nutrient permission sets.

1. In Setup, search for Permission Sets in quick find.

   
   

2. Open each relevant Nutrient permission set:

   • Nutrient_Admin
   • Nutrient_Sign_Documents
   • Nutrient_Signing_Integration
   
   

3. In each permission set, open External Credential Principal Access.

   
   

4. Click Edit.

   
   

5. Move the DWS signing principal, for example, NutrientDWSSigning - Signing Key from Available External Credential Principals to Enabled External Credential Principals.

6. Save.

   
   

Use this approach only for initial setup or sandbox testing. Package redeployments or upgrades can reset direct changes made to packaged permission sets, so this isn’t the recommended long-term production setup.

Option B — Recommended production setup

For production, create org-local permission sets and bundle them with the packaged Nutrient permission sets by using permission set groups.

1. Create a local credential-access permission set

Create a new permission set in your Salesforce org. Example name: Nutrient DWS Credential Access

1. In Setup, search for Permission Sets in quick find.

   
   

2. Open Permission Sets and click New.

   
   

3. Create the permission set and save it.

   
   

4. In the new permission set, open External Credential Principal Access.

   
   

5. Click Edit.

   
   

6. Enable access to the DWS signing principal, for example: NutrientDWSSigning - Signing Key

7. Save.

   
   

This permission set does only one thing: it enables users to use the stored DWS credential.

Optional: Add read access to User External Credentials

In some Salesforce orgs, non-admin signing users also need Read access to the User External Credentials object. If they don’t have it, they may see this error when they try to send an envelope: You don't have read permissions on the User External Credential object.

If your org requires this access, use one of these approaches:

• Add Read access to User External Credentials in your org-local Nutrient DWS Credential Access permission set.
• Or grant the same Read access in the affected users’ Salesforce profiles.

Do not rely on granting this access directly in the packaged Nutrient_Sign_Documents permission set. Package redeployments or upgrades can remove that change.

2. Bundle it with the relevant Nutrient permission sets

Create permission set groups for the main signing roles.

Then assign the appropriate permission set group to each user.

You can create and assign permission set groups by following these steps:

1. In Setup, search for Permission Set Groups in quick find.

   
   

2. Open Permission Set Groups and click New Permission Set Group.

   
   

3. Create the group and save it.

   
   

4. Open the group.

5. In the Permission Sets section, click Permission Sets in Group.

   
   

6. Add the required permission sets to the group.

   
   
   
   

7. Return to the group and click Manage Assignments.

   
   

8. Click Add Assignment.

   
   

9. Select the target users and click Next > Assign.

   
   
   
   

10. Verify that the users now appear in the assignment list.

Special case: API-only webhook integration user

If your webhook integration user uses the Salesforce API Integration license, it may also need read access to the User External Credentials object.

For this API-only user, create a separate org-local permission set and add it to the webhook permission set group. This is the recommended approach for that user type.

Create another local permission set. Example name: Nutrient UserExternalCredentials Access.

1. In Setup, search for Permission Sets in quick find.

   
   

2. Open Permission Sets and click New.

   
   

3. Create the permission set by using the Salesforce API Integration license.

   
   

4. Open Object Settings.

   
   

5. Open User External Credentials.

   
   

6. Click Edit.

   
   

7. Grant Read access.

8. Save.

   
   

9. Add this permission set to the webhook integration user’s permission set group.

   
   
   
   
   
   
   
   

Do not use a Salesforce administrator as the webhook integration user. Use a dedicated integration user with only the permissions needed for the signing integration.

How to validate this step

After granting access:

1. Open the Nutrient Admin tab.
2. Select Named Credential for Nutrient Signing.
3. Select Signing Integration User.
4. Click Test Connection.
5. Confirm that a regular signing user can send a document for signing.

If signing works for administrators but fails for regular users, those users likely don’t have external credential principal access.

5. Select named credential and signing user in Nutrient tab

1. Open the Nutrient Documents app in Salesforce.

2. Go to the Nutrient Admin tab.

3. In Named Credential for Nutrient Signing, select the named credential created above.

4. In Signing Integration User, select the integration user.

   • If this user isn’t ready yet, complete Part B, Step 1 first.

5. Save.

6. Click Test Connection and verify it succeeds.

   
   

Signing email templates

The installation creates a default signing email template. Salesforce admins can add additional signing email templates later as needed.

Configure a custom email domain in DWS

If your organization wants signer emails to come from your own domain, configure a verified custom email domain in the DWS Signer dashboard. If the domain is not already enabled for signing link sharing, contact our Sales team with the domain you want to set up. Our team can configure the signing_link_sharing flag for that domain in DWS, and then you can continue with the email domain setup explained below.

1. In the DWS Signer dashboard, click Email Domains in the left navigation panel and click Add Domain.

   
   

2. Select the Domain and, if needed, Return-Path Subdomain and click Save Domain.

   
   

3. Open Cloudflare(opens in a new tab) or whichever DNS hosting service you use, then configure the respective host and value there.

4. Return to the DWS Signer dashboard and verify and activate the domain after DNS propagation.

   The below screenshot is redacted to avoid exposing environment-specific DNS values.

   
   

Part B — Configure DWS webhooks to Salesforce (inbound)

DWS webhooks authenticate into Salesforce using OAuth 2.0 JWT Bearer Flow through an External Client App.

1. Prepare a dedicated integration user

Create or use a dedicated system user with:

• User License — Salesforce Integration
• Profile — Minimum Access - API Only Integrations

Assign the Nutrient Webhook with DWS permission set group.

2. Generate a key pair for JWT signing

JWT Bearer Flow requires an X.509 certificate (public key) and a matching private key.

Run:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout dws_jwt_private.pem \
  -out dws_jwt_certificate.crt \
  -subj "/CN=DWS Signer Integration/O=Your Company"

Use the generated files as follows:

• dws_jwt_certificate.crt — Upload to Salesforce External Client App
• dws_jwt_private.pem — Paste into DWS Salesforce integration settings

3. Configure the external client app for the JWT bearer flow

In Salesforce setup:

1. Search for External Client App Manager in quick find.

   
   

2. Open External Client App Manager.

3. Click New External Client App.

   
   

4. Fill basic information:

   • Name — DWS Signer Integration
   • Contact Email — admin email
   • Distribution State — Local
   
   

5. Enable OAuth and set:

   • Callback URL — https://login.salesforce.com/services/oauth2/callback
   • Selected OAuth Scopes:
     • Manage user data via APIs (api)
     • Perform requests at any time (refresh_token, offline_access)

6. Under Flow Enablement, enable JWT Bearer Flow and upload your public certificate (.crt).

7. Click Create.

   
   

8. Open the created app and go to the Settings tab.

9. In OAuth > Consumer Key and Secret, copy the Consumer Key. This is the client ID for DWS.

10. Open the Policies tab and click Edit.

11. In OAuth Policies, set Permitted Users to Admin approved users are pre-authorized.

    
    

12. In App Policies > Permission Sets, add Nutrient_Signing_Integration.

13. If Start URL is required in your organization, set a valid organization URL, for example https://your-domain.my.salesforce.com/lightning/page/home.

14. Save.

4. Configure the webhook destination in DWS Signer dashboard

In the DWS Signer dashboard(opens in a new tab):

1. Open Salesforce integration configuration from the left navigation panel.

   
   

2. Fill OAuth fields:

   • Salesforce Instance URL — Your Salesforce My Domain URL (for example, https://your-domain.my.salesforce.com)
   • Username — Salesforce integration user username
   • Consumer Key (Client ID) — Copied from External Client App settings
   • Private Key (PEM format) — Matching private key for the uploaded certificate

3. Set Webhook Endpoint to /services/apexrest/dwss-webhook.

4. Enable event subscriptions. For this app, select all events except envelope_created.

5. Save or enable the integration and confirm that it validates.

   
   

Add signing widgets to record pages

To let users start signing and track envelope status on Salesforce records, configure both signing-related widgets on the record page.

First, add the document creation widget that signing users use to start the flow. Refer to the set up document generation in Salesforce guide and use the Create and Send Document with Nutrient widget for users who send documents for signing.

Then add the signing status widget to each Salesforce record page where users should track signing progress.

1. Open the target record page in Lightning App Builder.
2. In the left component panel, find Nutrient Envelopes Widget.
3. Drag the component to the area where you want envelope status and sync actions to appear.
4. Optional: Add component visibility rules if only certain users or conditions should show the widget.
5. Click Save, and then click Activate.
6. Open a record and confirm that the widget loads correctly.

Validate the setup

Run this checklist after setup:

• Test Connection in Nutrient Admin succeeds
• A signing-enabled user can create/send an envelope from Salesforce
• Recipient can open the signing session and sign
• Envelope status updates appear in Salesforce after webhook events (for example, status becomes Completed)
• No auth/callout errors are shown in Salesforce logs

Troubleshooting

The following are common issues and resolutions.

Callout fails with auth errors

• Confirm the named credential URL and selected external credential.
• Verify APIKey value is present.
• Verify the Authorization header formula uses the correct credential name.
• Confirm principal access is granted to the user executing the callout.

DWS enable fails with OAuth credential validation failed

• Confirm Salesforce Instance URL uses My Domain (*.my.salesforce.com), not Lightning URL (*.lightning.force.com).
• Confirm the Consumer Key is copied from the same external client app where the JWT Bearer Flow was configured.
• Confirm the pasted private key matches the uploaded certificate.
• Confirm the uploaded certificate hasn’t expired. If expired, generate a new key pair, upload a new certificate to the external client app, and update the private key in DWS.
• In the external client app Policies, set Permitted Users to Admin approved users are pre-authorized.
• In App Policies > Permission Sets, add Nutrient_Signing_Integration.

Send fails with salesforce_integration_not_found

• Confirm the correct Named Credential for Nutrient Signing is selected in Nutrient Admin.
• In shared or preconfigured organizations, multiple named credentials may exist — pick the credential mapped to the active tenant/environment.
• If needed, ask the DWS team to enable Salesforce integration for your tenant/organization pairing.

Webhook events aren’t updating Salesforce

• Confirm the DWS webhook endpoint URL is correct (/services/apexrest/dwss-webhook).
• Verify the JWT Bearer Flow app configuration and key pair.
• Confirm the integration user is API-only and assigned the required permission set group.

Works for administrators but fails for regular users

• Regular users likely lack external credential principal access.
• Recheck the permission set group assignments for signing users.

Security and operations recommendations

• Rotate DWS Signer API keys regularly.
• Rotate Salesforce JWT certificates before expiration (for example, every 90–180 days based on your policy).
• Track certificate expiration dates with reminders or monitoring.
• During certificate rotation, overlap credentials to avoid downtime (upload the new certificate before removing the old one, and then update the DWS private key).
• Keep webhook integration users dedicated and least-privileged.
• Retest webhook delivery after package upgrades or auth changes.

Related guide

If your team also needs end user document generation instructions, refer to create documents in Salesforce.