Webhooks

When a job is completed or reviewed via the dashboard, Vouched can post the job results to a defined webhook URL. This can be set as callbackURL in the JS Plugin, the Submit Job or Send Invite API endpoint.

In order to distinguish webhook types you should check the X-WebHook-Eventhttp header the values as follows:

• job-reverifywhen a reverification job completes
• job-tin-validation see tin job docs for more information
• job-aml-monitoring-update for idv jobs with aml monitoring enabled
• job-idv-completewhen a regular IDV job completes, this will be the most common one
• job-dlv-completewhen DLV is enabled for IDV jobs
• job-review when a job is reviewed manually through the dashboard

Detailed explanation for each field can be found by clicking the 200 Provide Results on Jobs. under the Find Jobs page.

Approved/Rejected properties

In the above JSON response, the main field to check whether a job approved or rejected is result.success. This boolean field indicates Approved when True or Rejected when False.

Approved jobs can still have warnings we recommend checking. The field result.warnings is a boolean that indicates whether there are warnings on the job. If there are warnings, the field result.error can be checked to understand what warnings exactly.

Common warnings are: data-checks/crosscheck error, expired document, DLV error, and AML error.

Validating Webhook Responses

All webhook requests contain X-Signature in request headers. The X-Signature is base64 encoded, created using HMAC-SHA1 using your private key as the key and using the response as data. To validate the webhook response, perform the same signature procedure and confirm that your generated signature matches the sent signature.

Here is an example of validation from our Node.js sample repo.

Whitelisting

Please ensure the following IPs are whitelisted in order to receive webhook responses:

34.83.180.255
35.197.15.224

Custom Headers

Custom headers can be added to webhook requests for your account. Once set, the header is attached to every outbound webhook for the account regardless of job type.

Setting custom headers:

Use PUT /admin/accounts/:id with the following body:

{
  "webhookCustomHeaderName": "X-{{CUSTOM_NAME}}-Authorization",
  "webhookCustomHeaderValue": "abc123..."
}

Both name and value must be provided together, or both must be empty.

Updating Or Clearing custom headers

Send the pair again with new values to update or send with both empty to clear it

{
  "webhookCustomHeaderName": "",
  "webhookCustomHeaderValue": ""
}