Building best practices webhook listeners, part 3: Behind the firewall

By Larry Kluger and Joey Peng

This blog post is part 3 of a multi-part series on how to build secure webhook listeners. If you haven’t already, use the links below to catch up on part 1 and part 2.

In part 2 of this series, we discussed how you can use an asynchronous microservices architecture to process Connect webhook notifications. The following diagram shows the path for a notification message in this architecture.

In this scenario, the listener microservice responds to DocuSign after the message is enqueued. Your worker application, behind the firewall, then receives and processes the message asynchronously.

Worker applications behind the firewall

In many queuing systems, the worker application(s) can be located behind your company firewall.  To support this configuration, 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.


Installing the worker application behind your organization’s firewall enables easy access to your organization’s other corporate applications. As Sundar Pichai, Google CEO, commented in April, 2019: “Most enterprise applications are on-premises [behind the firewall].”

Many DocuSign developers have wanted to implement Connect webhooks but were stymied by networking issues. By using an asynchronous architecture with a queuing service, these problems are now solved: the worker application can live securely behind the firewall, with no firewall modifications needed.

The listener must be on the internet

The listener application must be available on the public internet to enable DocuSign Connect to make HTTPS POST requests to it. The listener can be easily and inexpensively implemented using serverless functions from Azure, AWS, Google Cloud, or other Platform as a service (PAAS) companies. Or the listener can be located on an organization’s DMZ network, available to clients on the internet.

Next time: Building a listener with AWS

Our next post will discuss an example scalable listener that uses an AWS Lambda serverless function to receive the notification messages, AWS Simple Queuing Service to queue them, and a worker application behind the firewall. The code examples are open source, so you’ll be able to try them yourself.

Larry Kluger
Larry Kluger
Lead Developer Advocate