Upon completion of the verification, AiPrise sends a callback to the set callback_url.

There are two ways to set the callback_url:

  • Set the callback_url at the template level
    • This can be set from the backoffice > View Templates > TemplateID
  • Set the callback_url with each verification request

Note: In case callback_url is set with the verification request, that will take precedence over the one set at the template level.

Authentication

How to make sure the request to your endpoint originates from AiPrise:

  • Make sure X-HMAC-SIGNATURE is present in the header
  • Generate the keyed hash of the payload using HMAC-SHA256 function and the API private key
  • Hex encode the hash
  • Compare the hex encoded hash with the X-HMAC-SIGNATURE header sent by AiPrise

How to know which callback corresponds to which request:

  • You can use the verification_session_id generated by AiPrise when the request was created.
  • You can pass an id in client_reference_id while creating the request. We pass this back in the callback.

Generating X-HMAC-SIGNATURE

  • Here are a few code examples on how to sign the request.

Example Payload

payloadAsString='{"verification_session_id": "123408f2-2bbb-415f-aafc-92212341234", "template_id": "123456-3434-2342-3453-b4218a4fb333", "client_reference_id": null, "aiprise_summary": {"tags": [], "reasons": [], "notes": [], "verification_result": "APPROVED"}, "created_at": 1668974142818}'

The result of the generated hash should be f8bf141ba610974d65f5dd603f7388474c366d1b95a13799748f92261610ba86 using code examples below with the API private key abcdef12-pqrs-abcd-pqrs-abcde0123456.

JavaScript / ECMAScript

const hashVal = crypto
  .createHmac('sha256', apiKey)
  .update(Buffer.from(payloadAsString, 'utf8'))
  .digest('hex')
  .toLowerCase();

console.log(hashVal);

Python

hash_val = hmac \
        .new(
            api_key.encode('utf-8'),
            msg=bytes(payload, encoding='utf-8'),
            digestmod=hashlib.sha256
        ) \
        .hexdigest() \
        .lower()

print(hash_val)

PHP

<?php
  $hashVal = strtolower(hash_hmac('sha256', $payloadAsString, $apiKey));
  echo $hashVal;
?>

C# / .Net

var hmacsha256 = new HMACSHA256(Encoding.UTF8.GetBytes(api_key));
var hash = hmacsha256.ComputeHash(Encoding.UTF8.GetBytes(payloadAsString));
var hashVal = Convert.ToHexString(hash).ToLower();

Console.WriteLine(hashVal);