Copy page

Developers

Webhook Signature Verification

This guide explains how Fluxis signs outbound webhooks and how to verify that (1) the request came from Fluxis and (2) the JSON body was not tampered with.

Implementation reference: src/pkg/utils/crypto_signature.go (GenerateRequestSignature, VerifyRequestSignature, toCanonicalJSON).

Related: Webhooks overview · API Integration Guide

::::note Account-level webhooks Webhook URLs and signing secrets are tied to an account (POST /v1/account/{accountID}/webhook), not to individual Points of Sale. Payment events include point_of_sale_id in the payload when relevant. ::::

What verification proves

Property	Meaning
Authenticity	Only someone with your webhook secret could produce a valid signature
Integrity	The JSON body was not modified in transit

Prerequisites

1. Webhook secret — Returned once in the response to POST /v1/account/{accountID}/webhook. Store it securely; it cannot be retrieved again.
2. HTTPS endpoint — Your server must accept POST with Content-Type: application/json.
3. Parsed body — Parse JSON first, then re-canonicalize for signing. Never sign raw request bytes.

Algorithm

Fluxis uses HMAC-SHA256 over a deterministic string built from the timestamp and the webhook body:

Code
signed_string = "<unix_timestamp_seconds>." + canonical_json(body)
signature     = hex( HMAC-SHA256( webhook_secret, signed_string ) )

Delivery headers:

Header	Value
X-Request-Signature	Hex-encoded HMAC-SHA256
X-Request-Timestamp	Unix seconds (string, e.g. "1712345678")
Content-Type	application/json

Timestamp validation: Reject if now - timestamp > 300 seconds (WEBHOOK_MAX_AGE_SECONDS). Future timestamps are not rejected by the current server implementation — you may add stricter checks in your handler if desired.

Signed object

Sign the entire webhook body as a JSON object, typically:

Code
{
  "data": {
    "notification_type": "payment_request_status_update",
    "payment_request_id": "aa5d6c80-0b0b-4a2a-bbc8-14a41e6245bf",
    "payment_request_type": "fixed",
    "external_reference_id": "order-123",
    "status": "completed",
    "point_of_sale_id": "3cc1f7ca-c017-4e7e-b00d-aca0da6e464e",
    "account_id": "c87464d1-c54a-48c3-80c9-bee4fddf593d"
  }
}

Do not sign only data, and do not sign the raw HTTP body string before parsing.

Canonical JSON rules

Fluxis builds canonical JSON via toCanonicalJSON:

1. Marshal the value to JSON (struct tags and omitempty apply — nil/zero fields are omitted).
2. Unmarshal into map[string]any / arrays so nested objects become maps.
3. Marshal again — Go json.Marshal on maps produces compact JSON (no spaces) with keys sorted alphabetically at every object level.

Your verifier must reproduce this behavior:

Rule	Detail
Compact	No spaces: {"a":1} not { "a": 1 }
Sorted keys	At every object level, including nested data
As received	Optional fields absent in the payload must stay absent in canonical form
Not raw bytes	Middleware that reformats JSON before verify will break signatures

::::note omitempty If external_reference_id or account_id is unset, those keys are omitted from the JSON Fluxis signs. Rebuilding the body from a fixed schema that always includes those keys will produce a different signature. ::::

Verification checklist

1. Read X-Request-Signature and X-Request-Timestamp from headers.
2. Parse the request body into a generic object (map / dict).
3. Reject if now - timestamp > 300.
4. Serialize the parsed object to canonical JSON (sorted keys, compact).
5. Build signed_string = timestamp + "." + canonical_json.
6. Compute HMAC-SHA256(secret, signed_string), hex-encode, and compare with constant-time equality (after a length check).

Worked example

Use these fixed values to test your implementation:

Input	Value
Secret	whsec_example_for_documentation_only
Timestamp	1712345678
Body	See JSON below

Body (parsed object):

Code
{
  "data": {
    "account_id": "c87464d1-c54a-48c3-80c9-bee4fddf593d",
    "external_reference_id": "order-123",
    "notification_type": "payment_request_status_update",
    "payment_request_id": "aa5d6c80-0b0b-4a2a-bbc8-14a41e6245bf",
    "payment_request_type": "fixed",
    "point_of_sale_id": "3cc1f7ca-c017-4e7e-b00d-aca0da6e464e",
    "status": "completed"
  }
}

Canonical JSON (single line):

Code
{"data":{"account_id":"c87464d1-c54a-48c3-80c9-bee4fddf593d","external_reference_id":"order-123","notification_type":"payment_request_status_update","payment_request_id":"aa5d6c80-0b0b-4a2a-bbc8-14a41e6245bf","payment_request_type":"fixed","point_of_sale_id":"3cc1f7ca-c017-4e7e-b00d-aca0da6e464e","status":"completed"}}

Signed string:

Code
1712345678.{"data":{"account_id":"c87464d1-c54a-48c3-80c9-bee4fddf593d","external_reference_id":"order-123","notification_type":"payment_request_status_update","payment_request_id":"aa5d6c80-0b0b-4a2a-bbc8-14a41e6245bf","payment_request_type":"fixed","point_of_sale_id":"3cc1f7ca-c017-4e7e-b00d-aca0da6e464e","status":"completed"}}

Expected signature (hex):

Code
174b7c02c84d9112e8013336ea632ae056b1c468387eca1815d3b1c24f5c0c49

If your implementation produces this signature for the inputs above, it matches Fluxis production signing.

---

Code examples

Node.js / TypeScript

Code
import crypto from "crypto";

function sortKeys(value: unknown): unknown {
  if (Array.isArray(value)) return value.map(sortKeys);
  if (value !== null && typeof value === "object") {
    return Object.keys(value as object)
      .sort()
      .reduce((acc, key) => {
        acc[key] = sortKeys((value as Record<string, unknown>)[key]);
        return acc;
      }, {} as Record<string, unknown>);
  }
  return value;
}

export function verifyWebhookSignature(
  payload: unknown,
  signature: string,
  timestamp: string,
  secret: string,
): boolean {
  const MAX_AGE_SECONDS = 300;
  const requestTimestamp = parseInt(timestamp, 10);
  if (Math.floor(Date.now() / 1000) - requestTimestamp > MAX_AGE_SECONDS) {
    return false;
  }

  const canonicalJson = JSON.stringify(sortKeys(payload));
  const signedString = `${timestamp}.${canonicalJson}`;
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(signedString)
    .digest("hex");

  if (signature.length !== expectedSignature.length) return false;
  return crypto.timingSafeEqual(
    Buffer.from(signature, "utf8"),
    Buffer.from(expectedSignature, "utf8"),
  );
}

::::warning Node.js timingSafeEqual crypto.timingSafeEqual throws if buffer lengths differ. Compare lengths first (as above), or use hmac.compare_digest in Python. ::::

Python

Code
import hmac
import hashlib
import json
import time

def verify_webhook_signature(
    payload: dict,
    signature: str,
    timestamp: str,
    secret: str,
) -> bool:
    MAX_AGE_SECONDS = 300
    request_timestamp = int(timestamp)
    if int(time.time()) - request_timestamp > MAX_AGE_SECONDS:
        return False

    canonical_json = json.dumps(payload, sort_keys=True, separators=(",", ":"))
    signed_string = f"{timestamp}.{canonical_json}"
    expected_signature = hmac.new(
        secret.encode("utf-8"),
        signed_string.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(signature, expected_signature)

Go

Matches production toCanonicalJSON and VerifyRequestSignature:

Code
func canonicalJSON(v any) ([]byte, error) {
    raw, err := json.Marshal(v)
    if err != nil {
        return nil, err
    }
    var generic any
    if err := json.Unmarshal(raw, &generic); err != nil {
        return nil, err
    }
    return json.Marshal(generic)
}

func verifyWebhookSignature(
    payload map[string]any,
    signature, timestamp, secret string,
) (bool, error) {
    ts, err := strconv.ParseInt(timestamp, 10, 64)
    if err != nil {
        return false, err
    }
    if time.Now().Unix()-ts > 300 {
        return false, fmt.Errorf("timestamp too old")
    }

    jsonBytes, err := canonicalJSON(payload)
    if err != nil {
        return false, err
    }
    signedString := fmt.Sprintf("%s.%s", timestamp, jsonBytes)

    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(signedString))
    expected := hex.EncodeToString(mac.Sum(nil))

    return hmac.Equal([]byte(signature), []byte(expected)), nil
}

---

Test your handler

1. Register a webhook: POST /v1/account/{accountID}/webhook with your public URL and event_type: "payment_request".
2. Save the secret from the create response.
3. Call POST /v1/account/{accountID}/webhook/{webhookID}/test — Fluxis POSTs a signed sample payload to your URL using the same code path as production (GenerateRequestSignature on { "data": … }).
4. Verify the signature in your handler and return HTTP 200.
5. Optionally compare against manual computation using the worked example above.

View delivery attempts in GET /v1/account/{accountID}/webhook/logs?page=1&page_size=20.

---

Common failures

Symptom	Likely cause
Signature always invalid	Wrong secret (not the one from create); signing raw body bytes instead of parsed JSON
Intermittent invalid	Optional fields added/removed vs what was signed; middleware mutating req.body
Valid signature, rejected anyway	Clock skew beyond 300s; using wrong timestamp (must match X-Request-Timestamp header)
Node handler crashes on compare	timingSafeEqual called with unequal-length hex strings — add length check first
Go mismatch on nested structs	Signing struct without round-trip through any — use canonicalJSON pattern above
Test works, production fails	Production payload missing fields your test vector always includes

Security notes

• Use constant-time comparison (hmac.Equal, hmac.compare_digest, timingSafeEqual with equal-length buffers).
• Reject stale timestamps (older than 300 seconds).
• Process business logic only after signature verification succeeds.
• Store the webhook secret in a secrets manager, not in source control.
• Use HTTPS for your endpoint; treat the secret like an API credential.

---

Need help?

Contact [email protected] with a redacted copy of the received body, headers (omit secret), and your computed canonical JSON if verification fails.