Integrations
API Keys
You can generate your API keys by visiting the Berbix Dashboard and navigating to the Integrations tab.


Within Integrations > API Keys
you can 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 in client-side and only used for server-side API requests.
Domains
Why do I need to list domains?
Domains ensure that the Berbix Verify Flow can only be instantiated using your credentials in the specific contexts you specify. This important security feature prevents bad actors from using your Berbix credentials to render the Berbix Verify Flow on a domain you do not control.
The Allowed Domains list allowlists a specified set of domains from which you expect to serve Berbix Verify. In the event that Berbix sees the Berbix Verify flow instantiated in a page on a non-allowlisted domain, Berbix will show a 403
error upon instantiating the Berbix flow.
Live and Test mode differences
Your domain and the pages hosting Berbix Verify must be being served over HTTPS in live mode. Test mode supports HTTP pages.
In test mode, you can use the
localhost
and127.0.0.1
hosts. Those hosts are not available in live mode.
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), such that you might need to add the same domain twice if you plan to use it both in test and 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 |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Webhooks
Webhooks fire to a specified endpoint when a transaction event occurs. There are two 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. This should only be utilized in unique circumstances as your application should typically respond to the client-side completion handler.
Webhooks
Pleae note: the Berbix webhooks described above run
POST
requests.
Retry attempts: We recommend using webhooks as an alternative to polling our system for transaction status updates. If Berbix receives a non-2xx response upon trying a given webhook, that webhook will be retried up to three times. 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
: actions associated with the transaction. This is 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 on 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
: actions associated with the transaction. This is the updated verification action post manual review.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"
}
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.Indeed, because 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 wouldn't otherwise have accepted. 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 4 months ago