Clause users with a DocuSign account can use the DocuSign Listener to enable their Smart Clauses to respond to DocuSign Connect events. 

How to configure your DocuSign account to send DocuSign Connect events to Clause:

  1. Log in to your DocuSign account via https://account.docusign.com
  2. Click your avatar at the top right. In the dropdown, choose "Go to Admin".
  3. From the Admin console, choose "Connect" from the left-hand side menu.
  4. Click "Add Configuration" and choose the "Custom" option.
  5. In the field "URL to Publish", type https://docusign-listener.clause.io
  6. Make sure to check the box to include "Time Zone Information". The listener requires the time zone offset to be included in the Connect event information.

In order for the DocuSign Listener to send a request to your Smart Clause, you must provide a Bearer Token and the clause ID or trigger URL. This can be done in one of two ways:

  1. Add clauseId and bearerToken query parameters to the DocuSign Listener URL so that the URL appears as follows (replace the placeholders with the actual values). To do this, make sure you have started with a Smart Clause on your contract in Clause where you will find these two values:
    https://docusign-listener.clause.io?clauseId=ABC&bearerToken=DEF
  2. Add custom fields to your DocuSign envelope with the names triggerUrl and bearerToken.  You must do this via your DocuSign account. From your avatar, select "Go to Admin". Select "Envelope Custom Fields". Add triggerUrl and bearerToken as custom fields. Now, when you create a new envelope in DocuSign, you will see "Envelope Custom Fields" below the recipient section where you can enter the correct values.

The trigger URL and Bearer Token for your Smart Clause can be found in the right-hand sidebar of the Clause contract editor under "Triggers":

Once the DocuSign Listener has been configured (using either method 1 or 2 above) it will send the DocuSign Connect events to the Smart Clause.

Simple Example Using docusign-connect Template

If you'd like to try out the DocuSign Listener with a simple example, try adding the docusign-connect Smart Clause from the Accord Project Library to your Clause contract. This Smart Clause listens for a specified envelope status event and increments a counter each time an event is emitted with that envelope status.

The docusign-connect template emits a notification obligation, which you can use to send a notification, such as an email or Slack message. From the Clause contract editor, you can configure your Smart Clause to send an email each time a notification is emitted from the Smart Clause via the right-hand sidebar under "Actions". Select the "Email" action to send a simple message via email.

Use the "Custom" action to use variables from the response, such as response.message.

{
  "$class": "io.clause.outbound.physical.alerts.email.EmailMessage",
  "contractId": metadata.contractId,
  "to": "<EMAIL>",
  "subject": "<SUBJECT>",
  "message": response.message
}

Advanced Example Using purchase-order-failure Template

If you'd like to try a more advanced template, add the purchase-order-failure Smart Clause to your contract on Clause. This Smart Clause will determine if a purchase order is received past the due date and issue a payment obligation for a penalty if late. The Smart Clause is stateful and will keep track of the total number of late purchase orders. When the number reaches the integer set as maxFailures, an additional charge will be added to the penalty. 

You can configure your Smart Clause to send an email with the amount owed or even trigger a Stripe payment to be made, described here.

Once you have a contract running on Clause with the purchase-order-failure Smart Clause, you can issue purchase order agreements from your DocuSign account. Each DocuSign envelope should include the following custom envelope fields: triggerUrl, bearerToken, actualPrice, currencyCode, and deliveryDate. You can create a template that pre-populates the triggerUrl and bearerToken with those from the Smart Clause. When the agreement is signed (signaling receipt of the order), the Smart Clause will be triggered and will check the time of receipt against the delivery date and emit a payment obligation if late.

Create Your Own Template

You can also create your own Smart Clause template that responds to DocuSign Connect events. A Smart Clause can utilize any of the following fields that are sent via a DocuSign Connect event, as illustrated in the model

The following envelope status fields are supported:

  • status ("Any", "Voided", "Created", "Deleted", "Sent", "Delivered", "Signed", "Completed", "Declined", "TimedOut", "Template", or "Processing")
  • envelopeId (String)
  • created (DateTime)
  • sent (DateTime)
  • delivered (DateTime)
  • signed (DateTime)
  • completed (DateTime)
  • email (String)

The following recipient fields are supported:

  • status ("Created", "Sent", "Delivered", "Signed", "Declined", "Completed", "FaxPending", or "AutoResponded")
  • email (String)
  • userName (string)
  • sent (DateTime)
  • delivered (DateTime)
  • signed (DateTime)
  • declined (DateTime)
  • declineReason (String)

The listener also supports envelope custom fields with properties:

  • name (String)
  • value (String)

If your DocuSign use case is not supported by this feature, please do not hesitate to let us know what is missing!