Asynchronous Processing
Please refer to API docs for the most up-to-date information.
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:
The document is submitted for processing with the
async
switch turned on{"async": true}
Veryfi processes the document and notifies your specified webhook URL (Before you get started, make sure that your webhook URL is configured correctly here)
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.
Webhook URL validation
A verification step has been added to our web portal in order to prevent private/invalid URLs.
When you change the Webhook URL in the settings/keys, we run a verification process:
A subscription event is submitted in a POST request to his Webhook URL with a secret payload.
Payload should contain a client-specific secret:{ "event": "subscription", "data": { "secret": "awdca8efquanvc8ahcwncw, "created": "2023-05-15 00:00:00" } }
A confirmation modal is shown, where the user has to enter the secret value. If it matches, the webhook URL will saved.
If an error occurs a modal will shown.
Restrictions:
You can't save without changes.
You can't use Veryfi's domain (veryfi.com).
https://webhook.site/'
is not allowed.You can save it empty in order to clean any pre saved URL.
You can only use HTTPS://
The link should be a public link.
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 look similar to this:
Success Webhook Post Request
}
"event": "document.created",
"data": {
"id": 123456789,
"created": "2021-10-20 15:27:26"
}
}
Failure Webhook Post Request
{
"event": "document.failed",
"data": {
"id": 123456789,
"created": "2021-10-20 15:27:26"
}
}
Please note, that after September 2023
Failure Webhook Post Request will be updated to
{
"event": "document.failed",
"data": {
"id": 123456789,
"created": "2023-08-10 19:11:32",
"error”: "<reason for failure>"
}
}
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 bodyclient_secret
- this can be found inside your Veryfi account herevalidation_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.
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;
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
Add webhook URL in the settings.
The URL should be an endpoint that accepts POST requests with JSON data and returns HTTP 200 response after receiving the request
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.
NOTES:
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
Read more about My Team and Permissions
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.
PS:
{"async": true}
/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 traditionaltrue/false
style of boolean.Read more about API Version 7 vs 8
If document processing fails, you will receive:
{
"event": "document.failed",
"data":{
"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.