Webhooks

Overview

Webhooks provide real-time notifications about verification status changes, eliminating the need for frequent API polling. By configuring a webhook URL, you can receive instant updates on verification events.

Setting up Webhooks

Provide Webhook URL

When initiating a verification request, include the webhook_url parameter in the request body.

Receiving Webhooks

Receive HTTP Request

When a verification event occurs, BIVE will send an HTTP POST request to your specified webhook_url.

Inspect Request Body

The request body will contain a JSON payload with the following structure:

{
  "event": "verification.completed",
  "data": PersonVerificationObject | BusinessVerficationObject
}

Verify Signature

• The request header will contain an X-Biveai-Signature key.

• Calculate the SHA256 hash of the request body using your API key.

• Compare the calculated hash with the value of the X-Biveai-Signature header.

• If the hashes match, the webhook is valid.

Implementation Examples

Example PHP / Laravel

// Retrieve the request's body
$input = json_encode(json_decode(file_get_contents("php://input"), true));
$secret = env("BIVEAI_WEBHOOK_SECRET");

// validate event do all at once to avoid timing attack
if($request->header('x-biveai-signature') !== ($ash = hash_hmac('sha256', $input, $secret)))
    exit();

Process Webhook Data

• Process the event data based on the event name.

Webhook Event List

Event Name	Description	Data Structure
verification.completed	Sent when a verification is completed	PersonVerficationObject | BusinessVerificationObject

Make sure your webhook endpoint can respond quickly (within a few seconds) to avoid timeouts.