> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bitrace.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Signatures Rules

> The signature ensures the request originated from the legitimate Bitrace AML provider, preventing malicious actors from sending fake webhook events (spoofing).

### Supported Signatures

* [x] MD5
* [ ] HMAC-SHA256 (Coming soon)

<Card title="Tools" icon="toolbox" href="https://api.bitrace.io/docs/tools/hash/">
  JSON Decoder & Hash Generator
</Card>

### Hash Calculation Rules

1. **Hash Calculation Scope**: Only the `data` object in the payload is used for hash calculation.
2. **Field Sorting and String Conversion**:

* Fields within the `data` object are sorted alphabetically.
* Each field is converted to a `key=value` format.
* Fields are joined using the `&` character.
* For nested objects within `data`, the same sorting and conversion rules apply.
* For arrays within `data`, elements are referenced using the format `array[index].field`, followed by the same sorting and conversion rules.

3. The computed Hash value is included in the HTTP response header as `x-encrypted-data`

#### MD5 Calculation Example

Assume the current secret key is `ABCDEFG123456`.

<Expandable title="Example Data">
  ```json theme={null}
  {
    "webhookId":"60944883389642198713019658195148",
    "data":{
      "dirData":{
        "in":{
          "default-kyt":{
            "strategyNo":"default-kyt",
            "strategyName":"default",
            "score":"22.27626",
            "details":[
              {
                "score":"22.27626",
                "code":"hack",
                "name":"Hacking"
              }
            ]
          },
          "default_62680284809793536_86437582530844820316382104768774":{
            "strategyNo":"default_62680284809793536_86437582530844820316382104768774",
            "strategyName":"3 hop｜All type ｜1% or 5000",
            "score":"22.27626",
            "details":[
              {
                "score":"22.27626",
                "code":"hack",
                "name":"Hacking"
              }
            ]
          }
        },
        "out":{

        }
      },
      "requestId":"60944883389642198713019658195148",
      "maxScore":"22.27626",
      "customId":"123456",
      "status":1003
    },
    "eventType":"getTxHashCustomRiskScore",
    "timestamp":"2025-05-29 11:25:23"
  }
  ```
</Expandable>

***

* **Step 1. Decode the `data` field in response into String**

<Expandable title="Convert in Key-Value Format">
  ```
  customId=123456&dirData.in.default-kyt.details[0].code=hack&dirData.in.default-kyt.details[0].name=Hacking&dirData.in.default-kyt.details[0].score=22.27626&dirData.in.default-kyt.score=22.27626&dirData.in.default-kyt.strategyName=default&dirData.in.default-kyt.strategyNo=default-kyt&dirData.in.default_62680284809793536_86437582530844820316382104768774.details[0].code=hack&dirData.in.default_62680284809793536_86437582530844820316382104768774.details[0].name=Hacking&dirData.in.default_62680284809793536_86437582530844820316382104768774.details[0].score=22.27626&dirData.in.default_62680284809793536_86437582530844820316382104768774.score=22.27626&dirData.in.default_62680284809793536_86437582530844820316382104768774.strategyName=3 hop｜All type ｜1% or 5000&dirData.in.default_62680284809793536_86437582530844820316382104768774.strategyNo=default_62680284809793536_86437582530844820316382104768774&maxScore=22.27626&requestId=60944883389642198713019658195148&status=1003
  ```
</Expandable>

* **Step 2. Concat the secret key as suffix**

<Expandable title="Concat Secret Key">
  ```
  customId=123456&dirData.in.default-kyt.details[0].code=hack&dirData.in.default-kyt.details[0].name=Hacking&dirData.in.default-kyt.details[0].score=22.27626&dirData.in.default-kyt.score=22.27626&dirData.in.default-kyt.strategyName=default&dirData.in.default-kyt.strategyNo=default-kyt&dirData.in.default_62680284809793536_86437582530844820316382104768774.details[0].code=hack&dirData.in.default_62680284809793536_86437582530844820316382104768774.details[0].name=Hacking&dirData.in.default_62680284809793536_86437582530844820316382104768774.details[0].score=22.27626&dirData.in.default_62680284809793536_86437582530844820316382104768774.score=22.27626&dirData.in.default_62680284809793536_86437582530844820316382104768774.strategyName=3 hop｜All type ｜1% or 5000&dirData.in.default_62680284809793536_86437582530844820316382104768774.strategyNo=default_62680284809793536_86437582530844820316382104768774&maxScore=22.27626&requestId=60944883389642198713019658195148&status=1003ABCDEFG123456
  ```
</Expandable>

* **Step 3. Calculate the MD5 Hash**

<Expandable title="Calculate">
  ```
  MD5(<string_in_step2>) = 1388efbf63c13bfa3c8c1bf32cb3a9d5
  ```
</Expandable>

* **Step 4. Compare the hash with the response header - x-encrypted-data**