Webhooks and Asynchronous Processing
Submit a document, receive a webhook, retrieve a document, handle errors
Helen Birulia avatar
Written by Helen Birulia
Updated over a week ago

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": true}

  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": true }

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 the 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/v8/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.


  • Only admins have permission to set up webhook URLs

  • Dev profiles aka “sandbox“ have separate api keys hence can have a different webhook URL in the settings

Webhook for Email collector

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.


  1. {"async": true}

  2. /api/v8/partner/documents/DOCUMENT_ID/

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

    Read more about API Version 7 vs 8

If document processing fails, you will receive:


"event": "document.failed",


"id": 123456789,

"created": "2021-10-20 15:27:26"



Webhook Errors and retries:

Veryfi sends a notification to a configured webhook URL.

Once document is processed, Veryfi will send a notification to webhook configured under the Settings/Keys page.

If our call to the webhook does not receive a success response in a timely manner (any response code < 400 considered successful), it tries 2 more times with an increasing wait period.

The default time-out settings are 3 seconds for the connection and 20 seconds for the response.

If all 3 webhook deliveries fail, an API Webhook Failed email will be sent to the configured admin* email address with document id(s).

Only 1 email is sent per 24-hour period listing all failed webhooks with document "id"s

*configured admin is the email of the company account owner.

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?