Skip to navigation
Platform 101WebhooksImplement Connect with your app

Create a webhook listener

View as Markdown

A webhook listener is an app that you create that exposes an endpoint URL that will receive event messages from Connect. The design and implementation of webhook listeners will vary widely and depend on your individual requirements and infrastructure, but all webhook listeners should be set up to:

  • Handle events on an Account level or an envelope level.

    An account-level listener receives event notifications for all envelopes associated with an account or a set of account users. You should use an account-level listener if:

    1. Envelopes are sent using the Docusign application (web app, mobile app), or another application where you do not have control over the envelope’s lifecycle.
    2. Your application needs the notifications for all envelopes in an account, or all envelopes from specific users in an account.
    3. Your application needs the same events to trigger notifications and you want Connect to send the same data.

    You can set your configuration to be account-level by creating a configuration via the API or the Admin interface. All envelopes created in the account will pass through the rules of the configuration and send out notification events based on the configuration. Account-level Connect is only available to specific Docusign plans.

    An envelope-level listener receives event notifications for specific envelopes. You should use an envelope-level listener if:

    1. The envelope is created via your application using the eSignature API, allowing you to add a webhook event during the envelope creation process.

    2. Your application only wants to receive envelopes that meet very specific conditions.

    3. Your application needs Connect to send different events and different data for each envelope.

      You can flag a new envelope to be tracked by Connect by using the eSignature API to create the envelope with an EventNotification object. As this envelope progresses through its lifecycle, it will send out notifications to your listener based on what you specified during the envelope creation. Setting Connect webhooks per envelope is available to all Docusign plans.

  • Handle messages in a supported format. The JSON SIM event model format is the most efficient choice and is recommended for all apps, but JSON aggregate, XML SIM, and XML aggregate formats are also supported. See JSON SIM event model and Legacy event message formats for details.

  • Always return a 200 status response to Docusign after receiving a message from Connect. If your application does not need a particular notification message, it should respond with a 200 to Docusign and then discard the message.

  • Have 99% or better availability, to avoid risking lost messages due to downtime. If this is difficult to achieve, you can use a PaaS (cloud) queuing system to receive the messages from Docusign and buffer them for your application. This configuration also enables your application server to receive the notifications messages behind your firewall with no changes to your firewall.

  • Respond to each request from Docusign within five seconds.

  • Use an asynchronous architecture. As a best practice, add incoming notification messages to an internal nonvolatile queue, and then send a 200 status response to Docusign. Use one or more worker processes to process the messages from the queue asynchronously.

Other considerations that can affect how you build your Connect listener include how receiving and queuing messages will interact with your corporate firewall. Creating small web services in the cloud to queue and route messages to your app can help avoid customizing your firewall settings.

Webhooks from behind the firewall

A major consideration for some developers can be how receiving and queuing messages will interact with your corporate firewall.

In many queuing systems, your worker application(s) may be implemented behind your company firewall, which can complicate the process of receiving notification messages. Creating a queuing and routing system in the cloud can help avoid customizing your firewall settings:

  • The client for the queuing system (the worker application) initiates the connection to the queuing system. Since the connection is outbound from behind the firewall, the worker application is able to receive incoming messages from the queuing system with no changes to the firewall’s standard configuration.
  • Many queuing systems enable this configuration including the Azure Service Bus, AWS Simple Queue Service, Google Cloud Pub/Sub cloud products, the Bee-Queue and Apache Kafka open source products, along with several others.

The listener application must be available on the public internet to enable Docusign Connect to make HTTPS POST requests to it. You easily and inexpensively implement a listener using serverless functions from Azure, AWS, Google Cloud, or other platform as a service (PaaS) companies. You can also choose to implement the listener on your organization’s DMZ network, available to clients on the internet.

Next steps