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
and127.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.
Example | Allows for | Does not allow for |
---|---|---|
https://www.berbix.com | https://www.berbix.com | https://berbix.com https://google.com http://www.berbix.com https://www.berbix.com:9999 |
https://berbix.com | https://berbix.com | https://www.berbix.com https://google.com http://berbix.com http://berbix.com:9999 |
https://*.berbix.com | https://www.berbix.com https://docs.berbix.com https://one.two.three.berbix.com | https://berbix.com https://google.com http://berbix.com http://berbix.com:9999 |
https://www.berbix.com:9999 | https://www.berbix.com:9999 | https://berbix.com https://google.com http://www.berbix.com https://www.berbix.com:8888 |
https://www.berbix.com:* | https://www.berbix.com:9999 https://www.berbix.com:8888 https://www.berbix.com | https://berbix.com https://google.com |
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 transactioncustomer_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 usetransaction_id
)transaction_id
: ID for associated transactioncode
: 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 toaccept
,reject
, orreview
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 occurredtransaction_id
: ID for associated transactioncustomer_uid
: customer UID associated with the transaction.type
: type of notification eitherevent
orerror
message
: more details of theevent
orerror
- Possible messages for events
SESSION_STARTED
: user has started a new sessionSESSION_FINISHED
: user has completed a session sessionPHOTO_ID_TYPE_PICK_STARTED
: user is picking their ID typePHOTO_ID_TYPE_PICK_COUNTRY_PICKED
: user has selected a country for their IDPHOTO_ID_TYPE_PICK_FINISH
: user has finished picking their ID typeDISALLOWED_PHOTO_DETECTED
: user has uploaded an invalid photo such as a US military IDPHOTO_ID_FRONT_STARTED
: user is on the step to upload the front of their IDUPLOAD_PHOTO_ID_FRONT_SUCCESS
: user has successfully uploaded the front of their IDPHOTO_ID_BACK_STARTED
: user is on the step to upload the back of their IDUPLOAD_PHOTO_ID_BACK_SUCCESS
: user has successfully uploaded the back of their IDSELFIE_VERIFICATION_STARTED
: user has started their selfie or liveness verificationUPLOAD_SELFIE_FINISH
: user has finished uploading their selfie or livenessBARCODE_SCAN_STARTED
: user has started a barcode scan for barcode-only verificationsBARCODE_SCAN_SUCCESS
: user has finished their barcode scan for barcode-only verificationsBARCODE_SCAN_FAILURE
: user has failed their barcode scan for barcode-only verificationsSUBMIT_DETAILS_VERIFICATION
: user has submitted their manual details
- Possible messages for errors
text_unreadable
: user uploaded an ID with unreadable textno_face_on_id_detected
: user uploaded an ID that should have a portrait, but is missing oneincomplete_barcode_detected
: user uploaded an ID that should have a barcode, but it could not be readunsupported_id_type
: user uploaded an unsupported ID typebad_selfie
: user uploaded a selfie that fails a selfie check such as livenessbad_upload
: user uploaded something that resulted in an error, and is not one of the above issues
- Possible messages for events
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 theSESSION_FINISHED
has acreated_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 theX-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.
Updated 9 months ago