Webhooks

📘

For System Integration Only

If you are using Bynn without system integration (no-code) or prefer receiving AML, KYC or KYB updates via email, webhook integration is not required. You can safely ignore webhooks in this case.

Why Use Webhooks?

When interacting with a third-party API like Bynn’s, two key challenges arise:

1. Services that don’t directly make an API request may still need to know the outcome.
2. Some events, such as AML matches or ongoing monitoring updates, occur independently of direct API calls.

Webhooks solve these problems by allowing you to register a URL that Bynn will automatically notify when an event happens. For example, if an ID verification is approved or rejected, Bynn will send an event notification to your webhook endpoint.

How Webhooks Work

1. Subscribe to Events – Register a webhook URL and choose which events you want to receive notifications for.
2. Receive Real-Time Updates – Whenever an event occurs (e.g., successful verification, AML match, document rejection), Bynn sends a structured JSON payload to your webhook URL.
3. Automate Actions – Use webhook data to trigger workflows, update your system, or notify your team in real time.

Access Webhook Settings

1. Navigate to Settings > Developer Settings (Webhooks) in your Bynn dashboard.
2. Here, you can configure webhook URLs to receive real-time updates to your platform.

Adding a Webhook Endpoint

1. Select the Live endpoint or specify a new URL.
2. Enter the Webhook URL (must be HTTPS).
3. Click Add to save the endpoint.

Subscribe to Webhook Events

We highly recommend subscribing to the following key events to ensure real-time updates on identity verification, compliance, and fraud prevention.

Decision Events

✅ decision.approved – Indicates that a decision has been reviewed and approved.
✅ decision.rejected – Triggered when a decision is reviewed and rejected.
✅ decision.challenge – Signals that a decision is being challenged or requires manual review by your team.

AML Events

✅ aml.screening.match – Triggered when an AML screening match is found, alerting you to potential risks and compliance concerns.

For a full list of webhook events and how to integrate them, see the event manager when clicking the Configure Event button inside your webhook configuration page.

🚧

Not receiving a webhook?

1. Double-check your event subscriptions – This is the most common reason for missing webhooks! Head over to your webhook settings, click “Configure Event,” and ensure you’ve selected the events you want to receive.
2. Verify your webhook URL – Make sure the URL you’ve entered is correct and publicly accessible. Even a small typo can cause issues!
3. Confirm you’re listening to the right environment – Are you testing in sandbox mode but expecting live webhooks (or vice versa)? Ensure you’re tuned in to the correct environment.
4. Check the webhook log – Visit the Webhook Logs page to see if there are any errors or failed attempts. This can help pinpoint the issue quickly!

Webhook Retry Policy

Webhooks will retry with the same Idempotency-Key in the header following an exponential backoff strategy:

• First 5 retries: Exponential backoff starting at 1 minute: 1, 2, 4, 8, 16, 32 minutes.
• Retries 6 to 10: Retries occur hourly (60 minutes).
• Retries 11 to 30: Retries occur every 6 hours (360 minutes).
• Retries 31 and beyond: Retries occur once daily (1440 minutes).

If there is no 2xx HTTP response from the server within the retry window (default 65 retries), the webhook will be discarded.

If your server experiences downtime exceeding the retry limit (default 40 days), you should re-sync from the webhook page. (And maybe have a serious talk with your dev team.)

Webhook Security

Bynn signs all webhooks using JWT (JSON Web Token) with RS256 encryption to ensure authenticity and integrity. You can read more about JWT and download JWT libraries at jwt.io.

How JWT Webhooks Work

1. JWT Payload in Webhook Body

   • The webhook payload includes the JWT under the jwt key in the JSON body.
   • You must decode the JWT using a JWT library and validate it with the RS256 algorithm.

2. Verify the JWT Signature

   • Use the Bynn Public RSA Key to validate the JWT signature.
   • If the signature is valid, you can trust that the webhook data has not been altered and that it was sent by Bynn.

Bynn Public RSA256 Key

Use the following public key to verify Bynn's JWT signatures:

-----BEGIN PUBLIC KEY-----  
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAgs4sO1z5s1ZAcrBJJXmB  
fZV69hSvXOLdYhLX7U7oYTV20KCW3xXM37m0bsh48Uq3JqrWVVnqNqNQI8U4ka4v  
4CR80OSWp2oAF/9ORigz/VCsddZ9X6UCkwl7qkhpW1yRBeuMeGWu7d6C43eOo+k/  
GqjDIrj3GI9DXRcVV/+68sBQVYFz8ybSEbkNsMJNoyz+oNU5zJyqB/Yq0A8D5Od8  
4M2nFD2pHEFF93tEmBR7VaPpK4+87NQ9u5cDEB49hkxm2F54scRNHwcHWQk/MUy1  
RZz0jkprASaj5HfcMXrr/KGdIIRxpJo7Ft4/tN+5YkAWX8Pg13++82uLUz0SsK/E  
BQIDAQAB  
-----END PUBLIC KEY-----

⚠️

Preventing Replay Attacks

• JWTs are signed with an expiration time to prevent replay attacks.
• If you decode a JWT too long after its creation, you may encounter an expiration error.
• If the JWT is expired, do not trust the webhook—instead, call the GET API corresponding to the webhook to retrieve the latest data.

✅

Trusted webhooks

• JWT signed webhooks ensure authenticity and prevent tampering.
• Always verify the signature with Bynn’s public RSA key before trusting the data.
• Check expiration timestamps to avoid using outdated webhook data.
• For expired JWTs, retrieve fresh data using the corresponding GET API.

Testing Webhooks

Webhook Event History

Webhook Example

Headers:

User-Agent: Bynn-Intelligence/v1.1
X-Webhook-Token: wh_5YCo6VqqfNWjNbMu8q3NPjct
X-Test-Mode: true
Content-Type: application/json
Idempotency-Key: wh_5YCo6VqqfNWjNbMu8q3NPjct

Payload:

{
  "event_id": "a5ba3848-94fc-47d6-b3eb-6687f4c033ea",
  "created_at": "2025-02-19T17:40:03Z",
  "event_type": "dossier.created",
  "resource": {
    "id": "dossier_P4Lm5gUnznF7UA6coyEP2NgN",
    "type": "dossier",
    "status": "in_progress",
    "name": "Test Person",
    "reference": "xxxxxxxxxxxxxxxxxx-your-unique-reference-for-the-resource",
    "created_at": "2025-02-19T17:40:03Z",
    "updated_at": "2025-02-19T17:40:03Z",
    "rel": {
      "url": "https://api.bynn.com/v1/dossiers/dossier_P4Lm5gUnznF7UA6coyEP2NgN"
    }
  },
  "organization": {
    "id": "acct_bbCRvLTkeCoH8eh3ZL7hRWGs",
    "name": "sdfsdf"
  },
  "jwt": "eyJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJieW5uLmNvbSIsInN1YiI6bnVsbCwiaWF0IjoxNzM5OTg2ODAzLCJleHAiOjE3NDAwNzMyMDMsImp0aSI6ImMyNjhlM2MyLWU4MTYtNDZmYS1iN2Q1LTRkNmJhZWY5Njc3MyIsImRhdGEiOnsiZXZlbnRfaWQiOiJhNWJhMzg0OC05NGZjLTQ3ZDYtYjNlYi02Njg3ZjRjMDMzZWEiLCJjcmVhdGVkX2F0IjoiMjAyNS0wMi0xOVQxNzo0MDowM1oiLCJldmVudF90eXBlIjoiZG9zc2llci5jcmVhdGVkIiwicmVzb3VyY2UiOnsiaWQiOiJkb3NzaWVyX1A0TG01Z1Vuem5GN1VBNmNveUVQMk5nTiIsInR5cGUiOiJkb3NzaWVyIiwic3RhdHVzIjoiaW5fcHJvZ3Jlc3MiLCJuYW1lIjoiVGVzdCBQZXJzb24iLCJjcmVhdGVkX2F0IjoiMjAyNS0wMi0xOVQxNzo0MDowM1oiLCJ1cGRhdGVkX2F0IjoiMjAyNS0wMi0xOVQxNzo0MDowM1oiLCJyZWwiOnsidXJsIjoiaHR0cHM6Ly9hcGkuYnlubi5jb20vdjEvZG9zc2llcnMvZG9zc2llcl9QNExtNWdVbnpuRjdVQTZjb3lFUDJOZ04ifX0sIm9yZ2FuaXphdGlvbiI6eyJpZCI6ImFjY3RfYmJDUnZMVGtlQ29IOGVoM1pMN2hSV0dzIiwibmFtZSI6InNkZnNkZiJ9fX0.SB3dfUZ3M3d4gdnM5y_5-m1_uEGKQO_TFjA0OPtjG5snLm3maaJkH-BxFkiuuw5JhNS3H8JClKkKJ_LuI9fW8mqEBXkgPVaYlB0aIdI7hmBszGNksdcXW58rrNbNaAy1nrt_AhWrLN9lN2qFZtIkFQRQv-GaZl7NIengWHyxoEKSqp00VCgTwFiMPYzJg3blUIjfaSpTmG_UO8zHw5G_sfuypwvY5oOosL7IP0y485hP57XlN3Lo78DpzUScgMf9N8u0GFiVwzJGMCArYdHS6MSOTSpY3y0pVBlNYGJ3UAEXHmAFvBsSp0ZU-QCkijBZtAGRzuRFq-401Ki9S4WRLA"
}

📘

About the Reference String

The Unique Reference String is the unique id you send when creating the verification session. It can be anything you want, like a email, UUID, token or user ID. Something so you can match the user on your side. Please avoid using PII as reference.

1. Check theIdempotency-Key – Webhooks are designed to be idempotent, meaning they should only be processed once. Double-check that you haven’t already handled the event to prevent duplicate processing.
2. Verify the JWT signature – Always validate the JWT (JSON Web Token) signature and extract data from the JWT object itself, rather than relying on data outside of it. This ensures that the webhook is authentic and tamper-free.
3. Retrieve full event data via API – If you need complete details about the event, make an API call to the resource -> rel -> url from the webhook using your Private Key. This will return the full dataset for a more thorough review.