Asynchronous Processing

While Veryfi's API is capable of extracting structured data from unstructured documents in just seconds, there might be business use cases when you need to process documents asynchronously.

This asynchronous flow is achieved with the use of Webhooks. The process works like this:

  1. The document is submitted for processing with the async switch turned on {"async": 1}

  2. Veryfi processes the document and notifies your specified webhook URL (Before you get started, make sure that your webhook URL is configured correctly here)

  3. The service that is serving your webhook makes a request to the Veryfi API to get the processed document's details.

This URL will be used as part of the asynchronous data extraction flow. Once a document that has been submitted for asynchronous data extraction has completed processing, the above URL will be used to notify your backend services.

Step 1: Submit a document for processing

Submit a document for processing using one of the methods described in the synchronous processing section inside your account API documentation.

Make sure that you enable asynchronous processing mode by adding this input parameter to the JSON request body:

{ "async": 1 }

The response will contain the document ID assigned to the document that is being processed. No additional information is available at this point as the document has not yet been processed.

{ "id": 123456789 }

Step 2: Receiving and validating the 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 and looks similar to this:

{ 
"event": "document.created",
"data": { "id": 123456789 }
}

In order to validate that this request was sent by Veryfi, a special validation header will be included in this request:

"x-veryfi-signature": "3awRveqxsYK5nB6Yjca4oq1ToV77ksq+sZ34ab7YoEq="

To validate the request, you will need 3 things:

  • payload - this is the entire JSON request body

  • client_secret - this can be found inside your Veryfi account here

  • validation_signature - this is the value of the x-veryfi-signature header in the request

The example code below demonstrates how to validate the incoming request.

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  

  1. Add webhook URL in the settings.

  2. The URL should be an endpoint that accepts POST requests with JSON data and returns HTTP 200 response after receiving the request

  3. Once document processing is complete, you will receive a similar request to your webhook:

curl --location --request POST 'https://webhook_address/webhook/veryfi' \ --header 'Content-Type: application/json' \ --data-raw '{"id": 41331192, "created": "2021-09-19 20:37:47" }'

{ "timestamp": "2021-09-20T18:54:13.375+00:00", "status": 400, "error": "Bad Request", "message": "", "path": "/v1/check/webhook/veryfi" }

Step 3: Retrieve processed document

Now that the webhook request has been validated as indeed coming from Veryfi, the next step is to retrieve the data extracted from the document and perform any additional required tasks.

To get the document's details, perform a GET request /api/v7/partner/documents/DOCUMENT_ID/ as described inside your Veryfi account here. DOCUMENT_ID can be found by accessing data.id in the JSON request body for the webhook request in step 2.

NOTES:

Only admins can set up webhooks.

If you have a dev profile “sandbox“ you can have a different webhook URL in the settings of your Dev sandbox.

Emailed documents when webhook URL is configured:

if a customer submits the document to their Veryfi account via email and they have a webhook URL configured on their account, Veryfi will then notify that webhook URL once the email is processed.

PS:

  1. {"async": 1}

  2. /api/v7/partner/documents/DOCUMENT_ID/

    These samples for v7, note that if you use v8, v8 abandons 1/0 style booleans for a more traditional true/false style of boolean.

    Read more about API Version 7 vs 8

If you experience any problems or need help setting this up, then please reach out to support@veryfi.com , we are here for you.


Did this answer your question?