Using the Post-assembly Processing Event Webhook to Modify Documents

Note: only users with the Site Administrator or Integration Administrator user role can manage webhooks.

The Post-assembly Processing Event webhook enables HotDocs Advance to notify your own web application of new assembled documents when a user completes an assembly. When it provides a successful response to Advance, your web application can then retrieve your assembled documents, modify them, and upload the amended documents back into Advance.

For example, you can insert a QR code from another system into an assembled document, then upload the document back into Advance. Additionally, you might want to replace your assembled documents with new documents that have not been assembled by Advance. For example, can you replace an assembled document in .DOCX format with a document in PDF format. 

Prerequisites

This webhook has the following prerequisites:

  • Creating a Webhook – you must have an existing webhook that:
    • Uses the Post-assembly processing Event type
    • Has access to the templates to which you want the webhook to apply
  • An endpoint on your web application that accepts a POST request

Only one Post-assembly processing Event webhook is permitted in each site.

Overview

When you create a post-assembly processing event webhook, you specify an endpoint on your own web application that accepts a POST request.

The post-assembly processing webhook activates when a user completes an assembly using a specific template. Advance sends data to your web application, detailing the assembled documents ready for modifications, replacement, or appending with additional documents. When the post-assembly processing webhook is activated, the work item details pane displays a message to the user that says post-assembly processing is in progress.

Once your documents have been retrieved and modified, your web application uploads them back into Advance and must then update the post-assembly processing status to Completed. When post-assembly processing is complete, Advance displays your modified documents in the work item details pane.

This is useful as it enables you to modify assembled documents outside of Advance in an application of your choice and send them back into Advance. For example, you might be assembling documents which you want to add a QR code to. When a user completes an assembly, Advance sends data to your QR code processing web application. Your web application can then retrieve your documents and insert a QR code on your documents. Once your documents have been processed, your web application uploads your modified documents back into Advance.

You can also replace your existing assembled documents. For example, you might be replacing an assembled document in .DOCX format with a PDF version. Your post-assembly processing application can convert your assembled document to PDF and send your replacement document back into Advance using the documentId. If you wish to keep the original document in .DOCX format and add a new PDF document to your set, your post-assembly processing application can upload your new document to Advance using a unique documentId.

Workflow

The POST request to your endpoint is activated when a user completes an assembly using a specific template. Advance sends data to your own application in which your documents are retrieved, modified, and uploaded back into Advance using a PUT request. When your documents are uploaded back into Advance, the post-assembly processing status is set to Complete using another PUT request.

You can optionally request your assembled documents from Advance when you use the post-assembly processing webhook to replace your assembled documents with new documents.

 

diagram of asynchronous workflow of post-assembly processing webshook

 

Your Existing Webhook

This example supposes that you have an existing webhook with the following properties:

  • Name – WebhookExample04
  • URL – https://localhost/WebhookExampleApp/PostProcessing
  • Event Type – Post-assembly processing Event (sends request to your own application to notify you of assembled documents that can be modified)
  • Authentication method – exampleHMAC
  • Active Status – Active
  • Untrusted SSL certificates – No

The URL for the webhook should point to the post-assembly processing endpoint in your own web application.

Authentication method

The token specified in the webhook is passed in the request sent to your endpoint, in the Authorization header. HMAC authentication is the recommended authentication method to authenticate requests from Advance to your own application.

See also Authentication Types

Data Sent from Advance to your Endpoint

When the post-assembly processing event webhook is activated by a user, the webhook sends a POST request to your endpoint. The request contains a JSON string that includes the following data:

  • userContextData — the user context data for the template; this includes details about the user that activated the webhook
  • Documents — the document data for the assembled documents in your work item
  • AnswerUrl — the URL of the assembled documents and answer files

For example:

{
    "userContextData":{
         "userId":"e9bc358f-945c-4bf0-8431-9e9fe5261813",
         "userFirstName":"Administrator",
         "userLastName":"User",
         "userEmailAddress":"administrator@example.com",
         "isClientInterview":false,
         "workGroupId":"3cbee577-4ab3-484c-a954-f71d82992e11",
         "workGroupName":"Work Group One",
         "userGroupIds":[
         "0": "baa86c59-98e7-4ce4-95e4-66a69b7c780c"
         ],
         "userGroups":[
         "0": "User Group One"
         ],
         "clientId":"00000000-0000-0000-0000-000000000000",
         "clientTitle":null,
         "clientFirstName":null,
         "clientLastName":null,
         "clientEmailAddress":null,
         "clientMobileNumberCountry":null,
         "clientMobileNumber":null,
         "workItemName":"Sample Work Item",
         "workItemId":"d5275304-35e9-4e61-9286-68294126f850",
         "workItemVersionId":"7e77d8c8-e9d9-4748-a5f7-a73138cefa4a",
         "siteMoniker":"moniker",
         "linkData":null,
         "templatePackageId":"1d63ce39-8544-4db5-91d9-154fd6cdd8ea",
         "templateName":"Sample Template",
         "templateVersionNumber":1
    },
    "documents":[
      {
         "documentId":"d794ae69-2e3c-53da-acb3-96111832cda7",
         "name":"Sample Document",
         "fileName":"Sample Document.docx",
         "mimeType":"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
         "createdDate":"2022-08-15T15:11:26.7824552Z",
         "assemblySessionId":"7e77d8c8-e9d9-4748-a5f7-a73138cefa4a",
         "hasContent":true,
         "assembledOrder":0,
         "url":"https://yourtenancy.hotdocsadvance.com/api/rest/v1.1/workitems/d5275304-35e9-4e61-9286-68294126f850/documents/d794ae69-2e3c-53da-acb3-96111832cda7/content"
      }
    ],
     "answerUrl":"https://yourtenancy.hotdocsadvance.com/api/rest/v1.1/workitems/d5275304-35e9-4e61-9286-68294126f850/answerfile/content",
     "relativeTimestamp":1660576288>
}

Once the webhook is activated, Advance expects a successful response from your web application application. Anything other than a 200-299 response will result in Advance setting the post-assembly processing status to PostProcessingFailed.

Get Documents from Advance via your Endpoint

When your application receives the notification from Advance, your web application must use the following GET request to get your assembled documents:

GET /WorkItems/{workItemId}/Documents/{documentId}/Content

Once your web application retrieves your documents, post-assembly processing can begin.

Upload Documents from your Endpoint to Advance

After modifying the documents, your web application must upload them back into Advance to enable the post-assembly processing status to complete.

Uploading your documents back into Advance

Your modified documents are limited to 30 megabytes.

Once your web application has modified the documents, it must use the following PUT request to upload the documents back into Advance:

PUT /WorkItems/{workItemId}/Versions/active/Documents/{documentId}/Content?name={name}&filename={filename}

You can also use the following PUT request using a specific work item version ID:

PUT /WorkItems/{workItemId}/Versions/{versionId}/Documents/{documentId}/Content?name={name}&filename={filename}

Your document must be in PDF or DOCX format. You must also set the content-type header for the request with the mime type that matches the content you are sending:

  • application/pdf — if the document you are uploading is a PDF document
  • application/vnd.openxmlformats-officedocument.wordprocessingml.document — if the document you are uploading is a DOCX document

The parameters for this request are:

Name Type Location Required Description
workItemId String Request URL Yes The ID of the work item.
documentId String Request URL Yes The ID of the document in your work item.
versionId String Request URL Yes The ID of the work item version.
name String Query string No The display name of the assembled document, shown in the work item details pane.
filename String Query string No The name and file extension of the file (docx or pdf).
assembledorder String Query string No See: Using the Post-assembly Processing Event Webhook to Add Documents

For more information, see the full Advance API documentation.

If you change the file extension of the filename parameter, the file type of the document you upload back into Advance must match. You must also ensure the MimeType in the request header matches the file type of the document you upload back into Advance.

Updating the Post-processing status

After your documents are uploaded back into Advance, your web application must use the following PUT request to update the post-assembly processing status:

PUT /WorkItems/{workItemId}/Versions/active/PostProcessingComplete

You can also use the following PUT request using a specific work item version ID:

PUT /WorkItems/{workItemId}/Versions/{versionId}/PostProcessingComplete

{
    isSuccess: true,
    message: "string"
}

Name Type Location Required Description
isSuccess Boolean Request body Yes The post-processing status of your document.
message String Request body No The message describing the reason for the post-assembly processing status outcome. Advance displays the message in the work item details pane. This is limited to 128 characters.

If post-assembly processing fails, you must use this request to indicate to Advance that post processing is incomplete for the work item. This is done by setting isSuccess to false.

If you do not update the post-assembly processing status within the time allocated by Advance, your work item will be set to Post-assembly processing failed and your documents will not be available to download. By default, you have 5 minutes to update the status. 

Retrying unsuccessful post-assembly processing

If post-assembly processing is unsuccessful, the user can relaunch the interview with the same answers by clicking Retry interview in the work item details pane. When the user finishes the interview, post-assembly processing will be reapplied to the assembled document. 

Webhook Restrictions

If you have Post-assembly processing and New Work Item Version Complete event webhooks configured, the post-processing status must be set to Complete before the New Work Item Version Complete event can activate.