General Integration Settings

The Integration section of the nav menu is now separated into General and Third-Party integration settings.

The General integration page is where you may add and manage API Keys, Allowed Domains, and Webhooks for use in your Low-Code or Full-Code integration.

API Keys

API keys may be accessed and generated visiting the Berbix Dashboard, and tapping "Integration" and "General" in the nav menu.

Within Integration > General > API Keys you may create a new API Secret by clicking Add Key.

Live API Secrets should be used in production environments and Test API Secrets should be used in testing environments.

API secrets are prefixed in the following format: secret_[mode]_ where mode is either live or test.

❗️

Never include your API secret(s) in client-side code

Your API secret(s) are required for requests to create transactions or fetch verification data. They should never be shared client-side and only used for server-side API requests.

Allowed Domains

The Allowed Domains are a specified set of domains from which you expect to serve Berbix verification transactions. In the event that Berbix sees a transaction instantiated in a page on a non-allowlisted domain, Berbix will show a 403 error.

📘

Why list allowed domains?

Domains ensure that Berbix verification transactions can only be instantiated using your credentials in the contexts you specify.

This important security feature prevents bad actors from using your Berbix credentials to render the Berbix on a domain you do not control.

To add a domain, simply click Add Domain, provide your domain name and click Submit. Please note that domains are associated to the mode they're created in (live or test), so you might need to add the same domain twice if you plan to use it both in test and live mode.

🚧

Live and Test mode differences

Live Mode: Your domain and the pages hosting Berbix verifications must be served over HTTPS in live mode.

Test Mode: HTTP pages are supported, and you may use http://localhost and 127.0.0.1 hosts. These hosts are not available in live mode.

To add wildcards to your domain name, use the * character. Wildcards can be used both to allow a range of subdomains or ports. We recommend using wildcards restrictively by specifying as much of the hostname's components as possible.

The table below outlines a few example values and their effects.

Webhooks

Webhooks fire from Berbix to your specified endpoint when a transaction event occurs. There are three types of transaction events:

• Verification status changed: When the verification result status has been updated. This should be used to respond to action changes after manual review.
• Verification finished: When the user completes a verification.
  • Note: This should only be utilized in unique circumstances, as your application should typically respond to the client-side completion handler.
• Verification progress (Beta): When the user makes progress on a transaction.

🚧

Please Note:

The Berbix webhooks described above run POST requests.

We recommend using webhooks as an alternative to polling our system for transaction status updates.

Retry attempts: If Berbix receives a non-2xx response upon trying a given webhook, that webhook will be retried up to two times after the initial attempt. We use exponential backoff to increasingly space out retries by a few seconds.

Webhooks are associated with Test or Live environments.

Webhooks will come from one of the following static IP addresses:

• 34.67.226.150
• 34.72.169.111
• 34.136.217.251
• 34.69.174.210
• 130.211.213.193
• 104.198.40.48
• 35.225.34.97
• 34.122.149.70

To test webhooks locally during development, you can set up a URL that redirects to localhost using ngrok.

Verification status changed event

The Verification status changed event hook can be used to update the verification action after a manual review in the Berbix dashboard.

The example below shows a sample verification finished webhook payload which includes:

• id: webhook event ID.
• transaction_id: ID for associated transaction
• customer_uid: customer UID associated with the transaction. This is omitted if not provided at transaction creation time.
• action: the updated verification action post manual review.
• dashboard_link: a URL to the corresponding transaction in the Berbix dashboard.

{
  "id": 012346547912823,
  "transaction_id": 123456789012,
  "customer_uid": "abc1234567", // Omitted if not provided at transaction creation time
  "action": "reject",
  "dashboard_link": "https://dashboard.berbix.com/transaction?orgId=123456789&transactionId=123456789"
}

Verification finished event

The Verification finished event hook can be used to notify your backend that a verification is complete and ready for data to be fetched via the API. This can be used in lieu of responding to the client-side completion handler in unique circumstances.

This is the recommended way to get notified that a verification is complete for the Hosted Flow. Please contact us if you are not using the Hosted Flow but believe that your integration requires consuming this webhook.

The example below shows a sample verification finished webhook payload which includes:

• user_id: deprecated field (please use transaction_id)
• transaction_id: ID for associated transaction
• code: deprecated field used for fetching verification data (use the access token instead returned in transaction creation API response)
• customer_uid: customer UID associated with the transaction. This is omitted if not provided at transaction creation time.
• action: the automated decision to accept, reject, or review the transaction based on your Action Maps.
• dashboard_link: a URL to the corresponding transaction in the Berbix dashboard.

{
  "user_id": 123456789012, // Deprecated field (use transaction_id instead)
  "transaction_id": 123456789012,
  "code": "012345678990", // Deprecated field used for fetching verification data (use the access token instead)
  "customer_uid": "abc1234567", // Omitted if not provided at transaction creation time
  "action": "reject",
  "dashboard_link": "https://dashboard.berbix.com/transaction?orgId=123456789&transactionId=123456789"
}

Verification progress (beta)

The Verification progress webhook can be used to keep track of end-user progress on their transaction. This webhook will surface a set of user events and errors that occur while they are going through the flow.

📘

Beta testing this webhook

While this webhook type is available for any Berbix customer to configure, it is currently undergoing beta testing and may be subject to future changes.

If you would like to set up this webhook, please notify [email protected] so we can monitor success and communicate any updates that may impact your use case.

You can create at most 2 hooks of this type.

The example below shows a sample verification progress webhook payload which includes:

• created_at: the time the event occurred
• transaction_id: ID for associated transaction
• customer_uid: customer UID associated with the transaction.
• type: type of notification either event or error
• message: more details of the event or error
  • Possible messages for events
    • SESSION_STARTED: user has started a new session
    • SESSION_FINISHED: user has completed a session session
    • PHOTO_ID_TYPE_PICK_STARTED: user is picking their ID type
    • PHOTO_ID_TYPE_PICK_COUNTRY_PICKED: user has selected a country for their ID
    • PHOTO_ID_TYPE_PICK_FINISH: user has finished picking their ID type
    • DISALLOWED_PHOTO_DETECTED: user has uploaded an invalid photo such as a US military ID
    • PHOTO_ID_FRONT_STARTED: user is on the step to upload the front of their ID
    • UPLOAD_PHOTO_ID_FRONT_SUCCESS: user has successfully uploaded the front of their ID
    • PHOTO_ID_BACK_STARTED: user is on the step to upload the back of their ID
    • UPLOAD_PHOTO_ID_BACK_SUCCESS: user has successfully uploaded the back of their ID
    • SELFIE_VERIFICATION_STARTED: user has started their selfie or liveness verification
    • UPLOAD_SELFIE_FINISH: user has finished uploading their selfie or liveness
    • BARCODE_SCAN_STARTED: user has started a barcode scan for barcode-only verifications
    • BARCODE_SCAN_SUCCESS: user has finished their barcode scan for barcode-only verifications
    • BARCODE_SCAN_FAILURE: user has failed their barcode scan for barcode-only verifications
    • SUBMIT_DETAILS_VERIFICATION: user has submitted their manual details
  • Possible messages for errors
    • text_unreadable: user uploaded an ID with unreadable text
    • no_face_on_id_detected: user uploaded an ID that should have a portrait, but is missing one
    • incomplete_barcode_detected: user uploaded an ID that should have a barcode, but it could not be read
    • unsupported_id_type: user uploaded an unsupported ID type
    • bad_selfie: user uploaded a selfie that fails a selfie check such as liveness
    • bad_upload: user uploaded something that resulted in an error, and is not one of the above issues

🚧

Use the created_at field rather than arrival time!

It is possible for events to arrive out of order. Using the provided created_at field is more reliable than using the timestamp the event arrived. Additionally, it is possible that the SESSION_FINISHED has a created_at field before the last success event due to processing times.

{
  "transaction_id": 1234123412341234,
  "customer_uid": "unique-uid",
  "type": "event",
  "message": "SESSION_STARTED",
  "created_at": "2022-12-16T22:48:40.693917311Z"
}

Webhook signatures

❗️

You should verify webhook signatures!

Our webhook requests include a cryptographic signature in the X-Berbix-Signature header. It is important that you check and validate that signature before trusting the contents of the payload.

Since the endpoint you're expecting Berbix to send requests to is open to the world, a bad actor could potentially impersonate Berbix and cause you to accept transactions you may otherwise have rejected.

By verifying the signature included in the request, you can be certain that the request was sent by Berbix and not by a bad actor.

Within the webhook configurator, you can also find the Hook Secret to be used for signature validation and Test your endpoint by issuing a sample webhook. Webhooks can be validated using the validateSignature method available in Berbix Server-Side SDKs. This method requires the following parameters:

• secret - This is the secret associated with that webhook available in the webhook settings page.
• body - The full request body from the webhook. This should take the raw request body prior to parsing.
• header - The value in the X-Berbix-Signature header.

var client = new berbix.Client({
  apiSecret: process.env.BERBIX_DEMO_CLIENT_SECRET,
});

const secret = "webhook_secret_on_dashboad"; // this secret key can be found in the webhook section of the dashboard
const body = "body_received_from_webhook_request"; // this is the body of the webhook request from Berbix
const signature = "x-berbix-signature header"; // content in the x-berbix-signature header, in the form v0,timestamp,signature

const isValid = client.validateSignature(secret, body, signature);

$client = new \Berbix\Client(
  getenv("BERBIX_DEMO_API_SECRET")));

$secret = "webhook_secret_on_dashboad"; // this secret key can be found in the webhook section of the dashboard
$body = "body_received_from_webhook_request"; // this is the body of the webhook request from Berbix
$signature = "x-berbix-signature header"; // content in the x-berbix-signature header, in the form v0,timestamp,signature

$isValid = $client->validateSignature($secret, $body, $signature);

cl = berbix.Client(api_secret=os.environ['BERBIX_DEMO_API_SECRET'])

# this secret key can be found in the webhook section of the dashboard
secret = "webhook_secret_on_dashboad"
# this is the body of the webhook request from Berbix
body = "body_received_from_webhook_request"
# content in the x-berbix-signature header, in the form v0,timestamp,signature
signature = "x-berbix-signature header"

is_valid = cl.validate_signature(secret, body, signature)

client = Berbix::Client.new(
  client_secret: ENV['BERBIX_DEMO_CLIENT_SECRET'],
)

# this secret key can be found in the webhook section of the dashboard
secret = "webhook_secret_on_dashboad"
# this is the body of the webhook request from Berbix
body = "body_received_from_webhook_request"
# content in the x-berbix-signature header, in the form v0,timestamp,signature
signature = "x-berbix-signature header"

is_valid = client.validate_signature(secret, body, signature)

BerbixClient berbixClient = Berbix.create(
    new Berbix.BerbixOptions.Builder()
        .apiSecret("YOUR_API_SECRET_HERE_DO_NOT_PUT_IN_SOURCE_CODE")
        .build());

String secret = "webhook_secret_on_dashboad"; // this secret key can be found in the webhook section of the dashboard
String body = "body_received_from_webhook_request"; // this is the body of the webhook request from Berbix
String signature = "x-berbix-signature header"; // content in the x-berbix-signature header, in the form v0,timestamp,signature
        
boolean isValid = berbixClient.validateSignature(secret, body, signature);

client := NewClient(os.Getenv("BERBIX_DEMO_TEST_CLIENT_SECRET"), &ClientOptions{})
    
secret := "webhook_secret_on_dashboad" // this secret key can be found in the webhook section of the dashboard
body := "body_received_from_webhook_request" // this is the body of the webhook request from Berbix
signature := "x-berbix-signature header" // content in the x-berbix-signature header, in the form v0,timestamp,signature

err := client.ValidateSignature(secret, body, signature) // err is nil if valid

Editing Webooks

To edit the webhook Target URL, click the Edit button, change the Target URL, then click Save. You can edit both your test URLs and your live URLs at any time.

© Berbix Inc. All rights reserved.