Payload and verification

This page documents the JSON body Kollect POSTs to your webhookUrl and how to verify X-Kollect-Signature.

HTTP request

Property	Value
Method	POST
Content-Type	application/json
Signature header	X-Kollect-Signature (lowercase hex)

Payload fields

Field	Type	Description
paymentId	string	UUID of the Kollect payment (id).
paymentReference	string	Smart Contract payment reference.
invoiceId	string	Invoice document id (string form of Mongo _id).
invoiceNumber	string	Human-readable invoice number.
status	string	Payment status after update (e.g. success, failed).
event	string	Upstream event: payment.confirmed or payment.failed.
transactionHash	string | null	On-chain transaction hash when applicable; null on some failure paths.
amount	string	Amount stored on the payment record (string).
currency	string	Payment currency (e.g. USDC-mainnet).
interface	string	Integration surface (e.g. kollect-server).
timestamp	string	ISO 8601 timestamp when the payload was constructed.

Example payload

{
  "paymentId": "550e8400-e29b-41d4-a716-446655440000",
  "paymentReference": "0xabc...",
  "invoiceId": "64a1b2c3d4e5f6789012345",
  "invoiceNumber": "INV-1001",
  "status": "success",
  "event": "payment.confirmed",
  "transactionHash": "0xdef...",
  "amount": "51.24",
  "currency": "USDC-mainnet",
  "interface": "kollect-server",
  "timestamp": "2025-03-23T12:00:00.000Z"
}

Signature algorithm

Kollect computes:

signature = HMAC_SHA256_hex( signingSecret, JSON.stringify(payload) )

The HMAC key is your signingSecret. The message is the JSON string of the payload object as produced by Kollect’s serializer for that request.

Verification strategies

1. Preferred: Read the raw request body bytes as received on the socket, compute HMAC over those bytes, and compare to X-Kollect-Signature. This avoids JSON normalization differences.

2. Alternative: Parse JSON, then JSON.stringify with a serializer that matches Kollect’s output. This is fragile if key order or spacing differs; prefer raw bytes.

Comparison

Use constant-time comparison (e.g. crypto.timingSafeEqual on equal-length buffers in Node.js) to reduce timing side channels.

Node.js example

const crypto = require("crypto");

function verifyKollectWebhook(rawBodyBuffer, signatureHex, signingSecret) {
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(rawBodyBuffer)
    .digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(String(signatureHex || ""), "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Idempotent processing

The same payment might generate multiple operational logs; your handler should upsert order state by paymentId (or invoiceNumber + your internal id) and ignore duplicate notifications if already processed.