Webhook Signature Verification

1. Overview

When VM sends a Webhook to a merchant callback URL, VM uses its private key to generate an RSA-SHA256 signature for the original HTTP request body.

After receiving the Webhook, the merchant should use the public key provided by VM to verify the signature and confirm that:

The message was signed by VM.

The request body was not modified during transmission.

2. Signature Rules

Item	Description
Signature algorithm	RSA-SHA256
Digest algorithm	SHA-256
RSA padding	PKCS#1 v1.5
RSA key length	2048 bits
Signed content	The exact original HTTP request body
Signature encoding	Base64
Signature header	`X-VM-SIGN`
Character encoding	UTF-8

Signature calculation:

signature = Base64(
    RSA_PKCS1_V1_5_SIGN(
        SHA256(raw_http_body),
        VM_private_key
    )
)

3. Webhook Request Example

HTTP header names are case-insensitive. The following names are equivalent:

X-VM-SIGN
X-Vm-Sign
x-vm-sign

HTTP/2 and some web frameworks may automatically convert header names to lowercase. This is expected behavior.

4. Signature Verification Process

Read the original HTTP request body.

Read the X-VM-SIGN request header.

Base64-decode the signature.

Use the VM Webhook verification public key to perform RSA-SHA256 signature verification.

Parse and process the JSON only after signature verification succeeds.

Reject the message if signature verification fails.

The original HTTP request body must be used for verification. Do not parse the JSON and serialize it again before verification. Any changes to whitespace, line breaks, field order, or escaping may cause signature verification to fail.

5. PHP Verification Example

6. Public Key

The merchant must use the VM Webhook verification public key:

-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----

Notes:

Do not use the merchant's own public key for verification.

Do not use the API public key configured for the merchant's requests to VM.

VM's private key will not be provided to the merchant.

Sandbox and Production public keys must be obtained separately and must not be assumed to be interchangeable.

The public key and its SHA-256 fingerprint should be obtained through a controlled channel.

Webhook Signature Verification

1. Overview#

2. Signature Rules#

3. Webhook Request Example#

4. Signature Verification Process#