Webhook Fundamentals

TrustID Cloud supports webhooks that will be triggered during events that your system may wish to act on. Integrating these into your application, enables it to act immediately when a particular event occurs, giving a more timely experience to users of your system.

The types of webhooks triggered will depend entirely on if your organisation has been configured to receive them. Webhook events are either on or off and cannot be toggled on a per scan basis. However, the Webhook address can be specified on a per scan basis.

Note

Please contact TrustID to ensure that all the webhook events you require have been configured for you.

Supported Webhook events

The following Webhook events are available:

  • ResultNotification This Webhook is triggered when a scan has completed processing and the result is ready for download. This Webhook event is always enabled.

  • ContainerSubmitted This Webhook event is triggered when a scan has been submitted for processing.

  • ContainerSentToReview This Webhook event is triggered when a scan cannot be automatically processed and has been sent for human intervention.

  • DocumentModifiedPostResult This Webhook event is triggered if a document is updated after the result is ready. This could be to correct a typo in the name, for example.

  • ContainerModifiedPostResult This Webhook event is triggered if a container is updated after the result is ready. This could be to correct a typo, for example.

Specifying your Webhook address

There are two ways to tell the TrustID Cloud the address to call for your webhook:

Note

Contact TrustID to set a webhook callback URL for your account.

Webhook Payload

The JSON format of each webhook request body is very similar, which can understandably make it difficult to understand the event that a certain response relates to.

{
  "Callback":
      {
            "Aborted": false,
            "CallbackAt": "/Date(1627478506239+0100)/",
            "CallbackId": "b748c867-60fd-4517-9e54-36db27152ec9",
            "CallbackStatusCode": 0,
            "CallbackUrl": "https://webhook.site/21b90916-864b-4403-b8ca2-f65ebce893b2",
            "ErrorMessage": null,
            "ProcessName": "DataAccess.PublishDocumentContainer",
            "RetryCounter": 1,
            "ScheduledAt": "/Date(1627478506239+0100)/",
            "State": 5,
            "UpdatedAt": "/Date(1627478506239+0100)/",
            "WorkflowName": "AutoReferral",
            "WorkflowState": "Stop",
            "WorkflowStorage": [
              {
                    "Key": "ContainerId",
                    "Value": "f36348e6-011e-4701-8437-f2873673e9fd"
              },
              {
                    "Key": "MergeContainers",
                    "Value": false
              },
            ]
      },
      "Response": {
            "ContainerId": "f36348e6-011e-4701-8437-f2873673e9fd"
      }
}

The Callback property will be the same for all webhook events. For information on the properties contained within see CallbackInfo.

In particular you shoud check the name of the workflow it’s in, by checking the CallbackInfo.WorkflowName. The following workflows exist:

  • AutoReferral From the point a container is submitted it enters this workflow, meaning it will be processed and automatically sent for human intervention if required.

  • UpdateDocumentContainer A container goes into this workflow if it is modified post result. This is not very common occurance.

  • UpdateDocument A container goes into this workflow if a document it contains is modified post result. This is not very common occurance.

You should also check the name of the state in the given workflow it is in, by checking CallbackInfo.WorkflowState.

Understanding Callback Context

To identify all responses that relate to a specific application/guestlink, please look at the following methods:

Method 1 - Custom value in ClientApplicationReference

You are able to attatch a custom string value to various requests, throughout your workflow. This string will then be returned to you, in any related callback request as an item in the CallbackInfo.WorkflowStorage list. Utilising this will allow you to link the given container to something within your own system. For informaion on setting the ClientApplicationReference see the following options:

  1. CreateDocumentContainerRequest.ClientApplicationReference

  2. CreateQueuedDocumentContainerRequest.ClientApplicationReference

  3. CreateGuestLinkRequest.ClientApplicationReference

Method 2 - Investigating Callback Response

You can use the Callback property of the webhook request you are sent. You should check the CallbackInfo.WorkflowStorage list, which will contain the unique identifier of the container within TrustID Cloud Container.Id.

Method 3 - Unqiue Callback Urls

When starting your workflow journey, set a unique callback URL, that when triggered, will allow you to identify the context by the URL itself. Consider the following examples

Example: Guest Link, for ‘John Smith’ == https://yourcompany.co.uk/trustid/callback/48cc6c7c-2e59-434c-9844-2ac21383a2a5/

Example: New Application, for ‘Alice Fletcher’ == https://yourcompany.co.uk/trustid/callback/1bf08902-7764-48c9-a109-cc9b376a9cc9/

Based on these examples, you would know that any request sent to ‘’https://yourcompany.co.uk/trustid/callback/48cc6c7c-2e59-434c-9844-2ac21383a2a5/’’, would be related to John Smith’s Guest Link.

It is worth noting, that if you fail to set an explicit callback URL when starting your workflow journey, then we will default to your static organisation’s callback url, that was specified when your organisation was first created.

Webhook Retries

If TrustID Cloud attempts to call your webhook and it fails it will retry 5 minutes later. The TrustID Cloud will make a total of 3 attempts to call your webhook. After this the event will be abandoned.

Because the TrustID Cloud is configured with a very short timeout when dispatching webhook events, you should respond immediately to avoid triggering a timeout response, which would lead to further attempts send the same request.

Note

The TrustID Cloud has a very short timeout when calling your webhook.

You should pay attention to the following properties to determine if the webhook is a duplicate call: