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 and 127.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.

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.

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: 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 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: 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 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.