# Webhook signature validator

> Validate BVNK webhook signatures client-side without sending sensitive data to external servers

When implementing BVNK's webhook system, signature validation is critical for security. The BVNK Webhook Signature Validator is a client-side tool that helps developers verify webhook signatures from BVNK's payment processing system. This tool allows you to:

- Validate webhook signatures without sending sensitive data to any external servers.
- Troubleshoot signature validation issues in your implementation.
- Compare your generated signatures against signatures received from BVNK.
- Identify configuration problems in your webhook handling code.

:::warning Security Note
All validation happens in your browser—no sensitive information is transmitted to any server, making this tool safe to use with production credentials.
:::

---

## How to use the validator

### Gather required information

Before using the validator, collect the following information:

| Field | Description |
|-------|-------------|
| **Secret Key** | Your unique webhook secret key provided by BVNK |
| **Webhook URL** | The complete URL where you receive webhooks (**Standard** only) |
| **Received Signature** | The signature value from the `X-Signature` header of the webhook |
| **Content Type** | The content type of the webhook, typically `application/json` (**Standard** only) |
| **JSON Payload** | The complete body content of the webhook |

### Enter information into the validator

1. Select the appropriate tab for your webhook type.
2. Enter your **Secret Key** in the designated field.
3. For **Standard** webhooks: Input the complete **Webhook URL**, including the protocol (`https://`).
4. Paste the **Received Signature** exactly as it appears in the `X-Signature` header.
5. For **Standard** webhooks: Verify the **Content Type** matches.
6. Paste the **JSON Payload** exactly as received, maintaining the same formatting (raw format).
7. Click the **"Validate Signature"** button.

The tool will process the information locally in your browser and display the results showing whether the signature is valid or invalid.

### Review diagnostic information

If the signature validation fails, review the diagnostic information section, which provides:

| Diagnostic Field | Description |
|------------------|-------------|
| **Webhook Path** | Shows the extracted path from the URL (**Standard** only) |
| **String Used for Generating Signature** | Displays the exact string that was used to create the signature |
| **Generated Signature** | The signature calculated by the tool |
| **Received Signature** | The signature you entered for comparison |

---

## Choose your webhook type

BVNK uses two different signature formats depending on the webhook service. Select the appropriate validator for your integration:

  

This validator is for webhooks that use **hexadecimal HMAC-SHA256** signatures. The signature is generated from the combination of webhook path, content type, and payload.

```json
{
    "source": "payment",
    "event": "statusChanged",
    ...
}
```

<iframe 
  src="/tools/bvnk-webhook-validator.html" 
  style={{
    width: '100%', 
    height: '520px', 
    border: '1px solid #e5e7eb', 
    borderRadius: '12px',
    backgroundColor: 'white'
  }}
  title="BVNK Webhook Signature Validator"
/>

  
  

This validator is for the new webhook service that uses **Base64 encoded HMAC-SHA256** signatures. The signature is generated solely from the payload.

```json
{
    "event": "bvnk:payment:crypto:status-change",
}
```

<iframe 
  src="/tools/bvnk-webhook-validator-hook-service.html" 
  style={{
    width: '100%', 
    height: '420px', 
    border: '1px solid #e5e7eb', 
    borderRadius: '12px',
    backgroundColor: 'white'
  }}
  title="New Service Webhook Validator"
/>

  

---

## Troubleshooting tips

<details>
<summary>Signature mismatch issues</summary>

- Ensure your **Secret Key** is entered exactly as provided by BVNK.
- Verify that your JSON payload maintains the **exact formatting** as received (no extra spaces or line breaks).
- Check that the **Content Type** matches exactly.
- For webhooks with query parameters, ensure the tool is extracting the correct path.

</details>

<details>
<summary>Common formatting problems</summary>

- **Whitespace differences**: The payload must match character-for-character, including all whitespace
- **Encoding issues**: Ensure special characters in the payload are preserved
- **URL encoding**: The webhook path should not include query parameters in the signature calculation

</details>

<details>
<summary>Comparing signatures</summary>

Use the diagnostic information to compare:
1. The **Generated Signature** from the tool
2. The **Received Signature** you entered

If they differ, check:
- Are you using the correct webhook type (Standard vs. New Hook Service)?
- Is your secret key correct?
- Is the payload exactly as received?

</details>