Docusign webhook message does not have way to diff

问题:

I have created 1 envelope with 2 composite templates with embedded signing and I can hook it up with the webhook event notification to receive a message once users finish signing, so I can try to update my db and download the file. However, the webhook response does not have the custom fields that I need to identify which file belong to which for me to update the db row.

This is my json serialized envelope example. Notice the custom field on each inline template, that have the property of DocuInfoId. I will need the value of those to update my db row

{
  "status": "sent",
  "emailSubject": "DocuSign API - Template Example",
  "eventNotification": {
    "url": "https:\/\/mytestsite.net\/api\/documentstuff\/docusign\/available",
    "loggingEnabled": "false",
    "requireAcknowledgment": "true",
    "useSoapInterface": "false",
    "soapNameSpace": "",
    "includeCertificateWithSoap": "false",
    "signMessageWithX509Cert": "false",
    "includeDocuments": "false",
    "includeEnvelopeVoidReason": "false",
    "includeTimeZone": "true",
    "includeSenderAccountAsCustomField": "false",
    "includeDocumentFields": "false",
    "includeCertificateOfCompletion": "true",
    "envelopeEvents": [
      {
        "envelopeEventStatusCode": "Sent",
        "includeDocuments": null
      },
      {
        "envelopeEventStatusCode": "Completed",
        "includeDocuments": "true"
      }
    ],
    "recipientEvents": [
      {
        "recipientEventStatusCode": "Completed",
        "includeDocuments": "true"
      }
    ]
  },
  "compositeTemplates": [
    {
      "inlineTemplates": [
        {
          "sequence": "1",
          "recipients": {
            "signers": [
              {
                "clientUserId": "1",
                "recipientId": "1",
                "email": "[e-mail]",
                "name": "Client Name",
                "roleName": "Client",
                "tabs": {
                  "TextTabs": "Just a bunch of text tabs, radio group, etc"
                }
              },
              {
                "clientUserId": "2",
                "recipientId": "2",
                "email": "[e-mail]",
                "name": "Owner Name",
                "roleName": "Owner",
                "tabs": null
              }
            ]
          },
          "customFields": {
            "ListCustomFields": [
              {
                "name": "DocuInfoId",
                "required": "True",
                "show": "False",
                "value": "77",
                "listItems": null
              },
              {
                "name": "OpportunityId",
                "required": "True",
                "show": "False",
                "value": "1",
                "listItems": null
              }
            ]
          }
        }
      ],
      "serverTemplates": [
        {
          "sequence": "1",
          "templateId": "TemplateIDNumber1"
        }
      ]
    },
    {
      "inlineTemplates": [
        {
          "sequence": "2",
          "recipients": {
            "signers": [
              {
                "clientUserId": "1",
                "recipientId": "1",
                "email": "[e-mail]",
                "name": "Client Name",
                "roleName": "Client",
                "tabs": {
                  "TextTabs": "Just another bunch of text tabs, radio group tab, etc"
                }
              }
            ]
          },
          "customFields": {
            "ListCustomFields": [
              {
                "name": "DocuInfoId",
                "required": "True",
                "show": "False",
                "value": "88",
                "listItems": null
              },
              {
                "name": "OpportunityId",
                "required": "True",
                "show": "False",
                "value": "1",
                "listItems": null
              }
            ]
          }
        }
      ],
      "serverTemplates": [
        {
          "sequence": "2",
          "templateId": "TemplateIDNumber2"
        }
      ]
    }
  ]
}

And once I finished signing, the webhook event notification is triggered and called my api with this response message

{
  "EnvelopeStatus": {
    "EnvelopeID": "EnvelopeIDGivenByDocusign",
    "Status": "Completed",
    "CustomFields": [
      {
        "Name": "ContactID",
        "Show": "True",
        "Required": "False",
        "Value": ""
      },
      {
        "Name": "OpportunityID",
        "Show": "True",
        "Required": "False",
        "Value": ""
      },
      {
        "Name": "AccountID",
        "Show": "True",
        "Required": "False",
        "Value": ""
      },
      {
        "Name": "DocuInfoId",
        "Show": "False",
        "Required": "True",
        "Value": "88"
      },
      {
        "Name": "OpportunityId",
        "Show": "False",
        "Required": "True",
        "Value": "1"
      },
      {
        "Name": "LQAID",
        "Show": "True",
        "Required": "False",
        "Value": ""
      }
    ],
    "DocumentStatuses": [
      {
        "ID": 1,
        "Name": "Document - TX - 1001.pdf",
        "TemplateName": "Document - TX",
        "Sequence": 1
      },
      {
        "ID": 2,
        "Name": "Rejection.pdf",
        "TemplateName": "Rejection Form",
        "Sequence": 2
      }
    ]
  },
  "DocumentPDFs": [
    {
      "Name": "Document - TX - 1001.pdf",
      "DocumentID": "1",
      "DocumentType": "CONTENT"
    },
    {
      "Name": "Rejection.pdf",
      "DocumentID": "2",
      "DocumentType": "CONTENT"
    },
    {
      "Name": "CertificateOfCompletion_78sd89fuas89sadf.pdf",
      "DocumentID": null,
      "DocumentType": "SUMMARY"
    }
  ]
}

Looking at the response, there's only 1 docuinfoid with the value of 88, I'm also not sure where is the rest of custom field coming from e.g: "LQAID". Now, I'm not sure which docuinfoid is this belong to, the first pdf file (Document - TX - 1001.pdf) or the second pdf file (Rejection.pdf).

Is there anyway to know which pdf document belong to which docuinfoid, so that I can attach it to my database correctly?

回答1:

You can set compositeTemplateId for each CompositeTemplate and then use this Id in each envelope Custom Field. I have modified your JSON request to include CompositeTemplateId,

{
  "status": "sent",
  "emailSubject": "DocuSign API - Template Example",
  "eventNotification": {
    "url": "https:\/\/mytestsite.net\/api\/documentstuff\/docusign\/available",
    "loggingEnabled": "false",
    "requireAcknowledgment": "true",
    "useSoapInterface": "false",
    "soapNameSpace": "",
    "includeCertificateWithSoap": "false",
    "signMessageWithX509Cert": "false",
    "includeDocuments": "false",
    "includeEnvelopeVoidReason": "false",
    "includeTimeZone": "true",
    "includeSenderAccountAsCustomField": "false",
    "includeDocumentFields": "false",
    "includeCertificateOfCompletion": "true",
    "envelopeEvents": [
      {
        "envelopeEventStatusCode": "Sent",
        "includeDocuments": null
      },
      {
        "envelopeEventStatusCode": "Completed",
        "includeDocuments": "true"
      }
    ],
    "recipientEvents": [
      {
        "recipientEventStatusCode": "Completed",
        "includeDocuments": "true"
      }
    ]
  },
  "compositeTemplates": [
    {
      "compositeTemplateId": "1",
      "inlineTemplates": [
        {
          "sequence": "1",
          "recipients": {
            "signers": [
              {
                "clientUserId": "1",
                "recipientId": "1",
                "email": "[e-mail]",
                "name": "Client Name",
                "roleName": "Client",
                "tabs": {
                  "TextTabs": "Just a bunch of text tabs, radio group, etc"
                }
              },
              {
                "clientUserId": "2",
                "recipientId": "2",
                "email": "[e-mail]",
                "name": "Owner Name",
                "roleName": "Owner",
                "tabs": null
              }
            ]
          },
          "customFields": {
            "ListCustomFields": [
              {
                "name": "DocuInfoId_1",
                "required": "True",
                "show": "False",
                "value": "77",
                "listItems": null
              },
              {
                "name": "OpportunityId_1",
                "required": "True",
                "show": "False",
                "value": "1",
                "listItems": null
              }
            ]
          }
        }
      ],
      "serverTemplates": [
        {
          "sequence": "1",
          "templateId": "TemplateIDNumber1"
        }
      ]
    },
    {
      "compositeTemplateId": "2",
      "inlineTemplates": [
        {
          "sequence": "2",
          "recipients": {
            "signers": [
              {
                "clientUserId": "1",
                "recipientId": "1",
                "email": "[e-mail]",
                "name": "Client Name",
                "roleName": "Client",
                "tabs": {
                  "TextTabs": "Just another bunch of text tabs, radio group tab, etc"
                }
              }
            ]
          },
          "customFields": {
            "ListCustomFields": [
              {
                "name": "DocuInfoId_2",
                "required": "True",
                "show": "False",
                "value": "88",
                "listItems": null
              },
              {
                "name": "OpportunityId_2",
                "required": "True",
                "show": "False",
                "value": "1",
                "listItems": null
              }
            ]
          }
        }
      ],
      "serverTemplates": [
        {
          "sequence": "2",
          "templateId": "TemplateIDNumber2"
        }
      ]
    }
  ]
}

Now, when you will receive WebHook response, you will be able to know which custom fields below to which composite template. I have one more suggestion, since you are not using any dropdowns, then it is better to use TextCustomFields instead of ListCustomFields.

回答2:

In DocuSign there are different types of custom fields.

• Envelope custom fields associate metadata with the Envelope as a whole.
• Document custom fields associate metadata with a specific Document in an Envelope.

To determine which type of custom fields your Create Envelope request is setting, you can execute the following requests for the envelope/document(s) and evaluate the results:

Get Envelope Custom Fields

GET /v2/accounts/{accountId}/envelopes/{envelopeId}/custom_fields

Get Document Custom Fields

GET /v2/accounts/{accountId}/envelopes/{envelopeId}/documents/{documentId}/fields

I'd suspect that perhaps your Create Envelope request is setting Envelope custom fields -- which associates that metadata with the Envelope as a whole, not with any specific document in the Envelope.

Based on what you've described, it sounds like you want to specify metadata for a particular document in an Envelope. If this is the case, you'll need to amend the structure/contents of your Create Envelope request to set Document custom field(s) (instead of setting Envelope custom fields).

回答3:

Instead of using the values from the CustomFields section of the XML, use the values contained in the TabStatuses elements.

You'll need to do a bit more parsing, but it gives you all the context info.