DocuSign Event Notification Include Documents being ignore on REST AP

Question

I am attempting to set up event notifications for envelope events and recipient events in docusign, however I am not getting the results I expect.

I am using the java model from the official java SDK, so I am presuming this is correct.

The code I have is thus:

private EventNotification createEventNotificationForRequest()
{
    EventNotification eventNotification = new EventNotification();

    eventNotification.setUrl(webhooksEnvelopeUpdateUrl);

    envelopeEventToIncludeDocumentsMap.forEach(
            (eventType, includeDocuments) ->
                    eventNotification.addEnvelopeEventsItem(
                            new EnvelopeEvent().envelopeEventStatusCode(eventType).includeDocuments(includeDocuments)));

    recipientEventToIncludeDocumentsMap.forEach(
            (eventType, includeDocuments) ->
                    eventNotification.addRecipientEventsItem(
                            new RecipientEvent().recipientEventStatusCode(eventType).includeDocuments(includeDocuments)));

    return eventNotification;
}

With the two maps created as such:

//We want to be notified of all events, and receive a copy of the document if it is completed
// Map<EventType, IncludedDocumentsBooleanAsString>
private static Map<String, String> envelopeEventToIncludeDocumentsMap = ImmutableMap.<String, String>builder()
        .put("Completed", TRUE)
        .put("Declined", FALSE)
        .put("Delivered", FALSE)
        .put("Sent", FALSE)
        .put("Voided", FALSE)
        .build();

private static Map<String, String> recipientEventToIncludeDocumentsMap = ImmutableMap.<String, String>builder()
        .put("AuthenticationFailed", FALSE)
        .put("AutoResponded", FALSE)
        .put("Completed", FALSE)
        .put("Declined", FALSE)
        .put("Delivered", FALSE)
        .put("Sent", FALSE)
        .build();

Based on this, my expected behaviour is that I would get event notifications via webhooks on the supplied url for every event type, however when the envelope is moved to the completed step we would also get the completed documents in the webhook. We are getting the events through ok but the completed document event notification does not send through to signed pdf copy.

With a small tweak, as seen below, I can change the EventNotification object so that it does return documents, however it now returns the document for every event and still ignores the includeDocuments fields on the specific events.

private EventNotification createEventNotificationForRequest()
{
    EventNotification eventNotification = new EventNotification();

    eventNotification.setUrl(webhooksEnvelopeUpdateUrl);
    // BELOW LINE IS CHANGE
    eventNotification.includeDocuments(TRUE);

    envelopeEventToIncludeDocumentsMap.forEach(
            (eventType, includeDocuments) ->
                    eventNotification.addEnvelopeEventsItem(
                        new EnvelopeEvent().envelopeEventStatusCode(eventType).includeDocuments(includeDocuments)));

    recipientEventToIncludeDocumentsMap.forEach(
            (eventType, includeDocuments) ->
                    eventNotification.addRecipientEventsItem(
                            new RecipientEvent().recipientEventStatusCode(eventType).includeDocuments(includeDocuments)));

    return eventNotification;
}

Is my expectation of this behaviour wrong, or are there any other issues that can be seen?

See below for snippet of relevant JSON sent:

  "eventNotification": {
    "envelopeEvents": [
      {
        "envelopeEventStatusCode": "Completed",
        "includeDocuments": "true"
      },
      {
        "envelopeEventStatusCode": "Declined",
        "includeDocuments": "false"
      },
      {
        "envelopeEventStatusCode": "Delivered",
        "includeDocuments": "false"
      },
      {
        "envelopeEventStatusCode": "Sent",
        "includeDocuments": "false"
      },
      {
        "envelopeEventStatusCode": "Voided",
        "includeDocuments": "false"
      }
    ],
    "recipientEvents": [
      {
        "includeDocuments": "false",
        "recipientEventStatusCode": "AuthenticationFailed"
      },
      {
        "includeDocuments": "false",
        "recipientEventStatusCode": "AutoResponded"
      },
      {
        "includeDocuments": "false",
        "recipientEventStatusCode": "Completed"
      },
      {
        "includeDocuments": "false",
        "recipientEventStatusCode": "Declined"
      },
      {
        "includeDocuments": "false",
        "recipientEventStatusCode": "Delivered"
      },
      {
        "includeDocuments": "false",
        "recipientEventStatusCode": "Sent"
      }
    ],
    "url": "{url_here}"
  }

Answer 1

Unfortunately the implementation of Connect has a bug. At this time you can either always or never receive the envelope's document(s) in the Connect notification messages.

If you're using account-level Connect subscriptions then a workaround is to create two subscriptions, one for just Envelope.Completed events. Then include docs for just the latter subscription.

In your case, you're using per-envelope subscriptions via the eventNotification object. Each envelope can have exactly zero or one such subscription.

Best practice suggestion: do not have the envelope's documents included in the eventNotifications. It causes the POST notifications to be very large and often problematic to process (on the DocuSign customer's side). Instead, use the notification as a trigger to get the envelope's documents, as needed.

Also, please be sure to ALWAYS return a 200 response to DocuSign. And do so quickly.

Recommended

When an event notification arrives at your server, add it to a FIFO reliable queue, and respond to DocuSign.

On a separate execution thread, have one or more worker processes process the messages on the queue.

NOT recommended

When an event notification arrives at your server, process it synchronously. When you're done processing it, respond to DocuSign.

This pattern will lead to big problems as your volumes increase, resulting in dropped notifications by your server, delays caused by resends, etc. You don't want to go there....