treezor-webhooks

Treezor Webhooks

When to Use This Skill

• How do I receive Treezor webhooks?
• How do I verify the Treezor object_payload_signature?
• Why is my Treezor webhook signature verification failing?
• How do I handle Treezor events like payin.create, cardtransaction.create, or user.kycreview?
• How do I subscribe to Treezor webhooks via the API?

Verification (core)

Treezor uses a custom HMAC-SHA256 scheme — not Standard Webhooks — and the signature is a field inside the JSON body, not an HTTP header. Webhooks arrive with a text/plain MIME type, so parse the body yourself.

Each body carries object_payload (the object data) and object_payload_signature. To verify, re-serialize object_payload to Treezor's canonical form (the same string PHP's json_encode produces): compact separators, forward slashes escaped (/ → \/), and non-ASCII escaped to lowercase \uXXXX. Then HMAC-SHA256 it with your webhook_secret, base64-encode, and compare timing-safe.

Node:

const crypto = require('crypto');

function canonicalize(objectPayload) {
  // Match PHP json_encode: compact, slashes escaped, non-ASCII as \uXXXX
  return JSON.stringify(objectPayload)
    .replace(/\//g, '\\/')
    .replace(/[\u0080-\uffff]/g, (ch) =>
      '\\u' + ch.charCodeAt(0).toString(16).padStart(4, '0'));
}

function verify(objectPayload, receivedSignature, secret) {
  if (!receivedSignature) return false;
  const expected = crypto.createHmac('sha256', secret)
    .update(canonicalize(objectPayload), 'utf8')
    .digest('base64');
  try {
    return crypto.timingSafeEqual(Buffer.from(receivedSignature), Buffer.from(expected));
  } catch {
    return false; // length mismatch = invalid
  }
}

Python:

import hmac, hashlib, base64, json

def canonicalize(object_payload) -> str:
    # ensure_ascii escapes non-ASCII to \uXXXX; compact separators; escape slashes
    return json.dumps(object_payload, ensure_ascii=True, separators=(",", ":")).replace("/", "\\/")

def verify(object_payload, received_signature: str, secret: str) -> bool:
    if not received_signature:
        return False
    expected = base64.b64encode(
        hmac.new(secret.encode(), canonicalize(object_payload).encode(), hashlib.sha256).digest()
    ).decode()
    return hmac.compare_digest(received_signature, expected)