Sync vs Async Processing

The synchronous/asynchronous document processing is controlled by the async request parameter. By default the async parameter is false, so all the documents processed synchronously return the extracted data in the response.

Parameters

---

• asyncBoolean

  Optional flag to enable asynchronous processing mode. Set to false by default.

  ---

info

Only Receipt and Invoice document types support synchronous and asynchronous document processing.

Synchronous Processing

Veryfi's API is capable of extracting structured data from unstructured documents in just seconds. To get the extracted data instantly the synchronous processing is the best choose.

Synchronous processing workflow

1. Document is submitted for processing with a POST request async parameter been set to false
2. Veryfi processes the document and returns an instant response with all the extracted document data

Asynchronous Processing

Asynchronous processing is ideal when submitting multiple documents simultaneously for batch processing. The Documents API will send a notification to the webhook configured when the documents are processed and ready to be consumed. This asynchronous flow is achieved with the use of webhooks.

Asynchronous processing workflow

1. Document is submitted for processing with the async switch turned on
2. Veryfi processes the document
3. Veryfi makes a request to the webhook URL
4. The service that is serving your webhook makes a request to the Veryfi API to get the processed document's details

Step 1: Configure your webhook URL

Your webhook URL is tied to your user profile and can be configured in Profile Keys Section.

info

Make sure your webhook responds with a 200 HTTP Status Code in a timely manner, under 10 seconds. It will need to be able to process requests similar to the one in receiving and validating the webhook request

Sample webhook request using cURL

curl --location --request POST 'https://{YOUR_WEBHOOK_URL}/' \
    --header 'Content-Type: application/json' \
    --header 'x-veryfi-signature: 3awRveqxsYK5nB6YjcaMoq1Tov87ksq+YZ34ab7YoEq=' \
    --data-raw '{"id": 41331192, "created": "2021-09-19 20:37:47"}'

Step 2: Submit a document for processing

Submit a document for processing using one of the methods described in the document processing sections above. Make sure that you enable asynchronous processing mode by adding the following input parameter to the JSON request body:

Parameters

---

• asyncBoolean

  Optional flag to enable asynchronous processing mode. Set to false by default.

  ---

Returns

---

• idInt

  The response will contain the Document ID assigned to the document that is being processed. No additional information is available as the document has yet to be processed.

  ---

Sample Async Processing Response

{
  "id": 123456789
}

Step 3: Receive a webhook request

Within seconds of submitting a document for processing, you will receive a webhook POST request to your specified webhook URL. The request body will be in JSON format

Parameters

---

• eventString

  The status of the document sent for processing.
  document.created - the document has been processed and is ready to be retrieved.
  document.failed - document processing has failed.
  

  ---

• dataObject

  JSON object that contains the extracted information from the processed document.

  ---

• idInt

  The ID of the processed document.

  ---

• createdDatetime

  The date-time indicating when the processed was processed.

  ---

If the async request succeeds, the webhook event will be:

Example of a successful webhook request

{
    "event": "document.created",
    "data": {
        "id": 123456789,
        "created": "2021-10-20 15:27:26"
    }
}

If the async request fails, the webhook event will be:

Example of a unsuccessful webhook request

{
    "event": "document.failed",
    "data": {
        "id": 123456789,
        "created": "2021-10-20 15:27:26"
    }
}

Step 4: Validate the webhook request

Your application should validate that Veryfi is the service that sent the webhook request. Securing sensitive data and safeguarding your application and servers from misuse is essential. Veryfi includes a validation header in the webhook request so that your application can validate that Veryfi sent the inbound request. This optional step adds an extra layer of security to prevent spoofing of the webhook call.

Document processing workflow for webhooks

Once a document is processed, Veryfi will send a notification to the configured webhook.

info

If Veryfi does not receive a success response in a timely manner (any response code < 400 is considered successful), it tries three more times with an increasing wait period. The default time-out settings are 3 seconds for the connection and 20 seconds for the response, and the maximum repeats per request is 4.

If all three webhook deliveries fail, two API webhook failed emails will be sent to configured admin email address:

1. The first email will include the first failed document id.
2. The second email will contain all the document ids that failed to receive a successful webhook response.

To validate the incoming request, you will need

---

• payloadREQUIREDObject

  The entire JSON request body.

  ---

• client_secretREQUIREDString

  The Client Secret can be found in the Keys section.

  ---

• validation_signatureREQUIREDString

  The value of the x-veryfi-signature header in the request.

  ---

Example x-veryfi-signature header

"x-veryfi-signature": "3awRveqxsYK5nB6YjcaMoq1Tov87ksq+YZ34ab7YoEq="

Sample code for validating the webhook request

Python

import hashlib
import hmac
import base64
from typing import *

def create_signature(data_payload: Dict, client_secret: str) -> str:
    signature = hmac.new(
        client_secret.encode("utf-8"), msg=str(data_payload).encode("utf-8"), digestmod=hashlib.sha256
    ).digest()
    base64_signature = str(base64.b64encode(signature), "utf-8").strip()
    return base64_signature

generated_signature = create_signature(payload["data"], client_secret)

# Confirm that the generated signature equals the validation signature
# from the x-veryfi-signature header
is_valid = generated_signature == validation_signature

Javascript

function createSignature(payload, clientSecret) {
 return crypto
   .createHmac("sha256", clientSecret)
   .update(
     JSON.stringify(payload.data)
       .replace(/,/g, ", ")
       .replace(/":/g, '": ')
       .replace(/"/g, "'")
   )
   .digest("base64");
}


const generatedSignature = createSignature(payload, clientSecret);
const isValid = generatedSignature === validationSignature;

PHP

<?php
function arrayToPythonDictString($arr) {
    $items = [];
    foreach ($arr as $key => $value) {
        $items[] = "'" . $key . "': " . $value;
    }
    return "{" . implode(", ", $items) . "}";
}
function create_signature($data_payload, $client_secret) {
    $data_string = arrayToPythonDictString($data_payload);
    $signature = hash_hmac('sha256', $data_string, $client_secret, true);
    $base64_signature = base64_encode($signature);
    return trim($base64_signature);
}

$generated_signature = create_signature($payload["data"], $client_secret);

// Confirm that the generated signature equals the validation signature
// from the x-veryfi-signature header
$is_valid = ($generated_signature === $validation_signature);

?>

Step 5: Retrieve the processed document

Now that the webhook request has been validated as coming from Veryfi, the next step is to retrieve the data extracted from the document. To retrieve the Document's details, perform a GET request on the Document enpoint.

To retrieve the document, you will need

---

• document_idREQUIREDInt

  The unique identifier of the document. The JSON request body for a successful webhook request will contain the Document's ID.

  ---

Performing a GET request by the Document's ID will return the fully extracted details of the processed document in JSON format.