How We Built Cryptographic Invoice Signatures for a SaaS Invoicing Platform

Reinvoice LLC — Sat, 06 Jun 2026 18:21:00 +0000

How Reinvoice Uses HMAC Signatures to Detect Invoice Tampering

Every invoice sent through Reinvoice includes a cryptographic integrity signature.

It is not a PDF stamp, a visual badge, or a checkbox. It is an HMAC-SHA256 hash generated from the invoice payload and a server-side signing secret. If signed invoice data changes after creation, Reinvoice can recompute the hash, compare it to the stored signature, and flag the invoice as potentially tampered with.

Here is why we built it, how it works, and what we learned.

Why Integrity Checks Matter for Invoicing

Invoices are high-value documents. A single altered field could change a payment amount, tax calculation, client record, or audit trail.

Most invoicing systems treat invoices as ordinary database records. That works for normal CRUD workflows, but it does not automatically prove that the invoice data being viewed today is the same data that was created and sent.

Reinvoice adds an integrity layer.

When an invoice is created, we sign the fields that define the invoice. Later, when someone verifies the invoice, we recompute the signature from the current data and compare it against the original stored signature. If the values do not match, the invoice is flagged.

The Implementation

The signature is stored in two places: on the invoice record in the database, and behind a public verification endpoint.

import { createHmac, timingSafeEqual } from 'node:crypto';

const SIGNATURE_FIELDS = [
  'invoiceNumber',
  'issuerName',
  'clientName',
  'totalAmount',
  'currency',
  'taxAmount',
  'issuedAt',
  'dueDate',
  'lineItems',
  'notes',
  'subtotal',
  'discountAmount',
  'shippingAmount',
] as const;

export function generateInvoiceHash(invoice: InvoiceData): string {
  const payload = SIGNATURE_FIELDS.map((field) => {
    const value = invoice[field as keyof InvoiceData];
    return `${field}=${JSON.stringify(value)}`;
  }).join('|');

  return createHmac('sha256', SIGNING_SECRET)
    .update(payload)
    .digest('hex');
}

The verification endpoint accepts an invoice identifier or verification token, loads the invoice, recomputes the hash, and checks whether the stored signature still matches the current invoice data.

export async function verifyInvoiceSignature(invoiceId: string): Promise<boolean> {
  const invoice = await db.query.invoices.findFirst({
    where: eq(invoices.id, invoiceId),
  });

  if (!invoice?.signatureHash) return false;

  const expectedHash = generateInvoiceHash(invoice);

  const actual = Buffer.from(invoice.signatureHash, 'hex');
  const expected = Buffer.from(expectedHash, 'hex');

  if (actual.length !== expected.length) return false;

  return timingSafeEqual(actual, expected);
}

We use timingSafeEqual instead of a normal string comparison because signature comparison should not leak useful timing information to an attacker.

Why HMAC Instead of Public-Key Signatures?

HMAC-SHA256 is a good fit for our current use case because verification is server-mediated. The signing secret stays on the Reinvoice server, and recipients verify invoices through a public endpoint rather than verifying locally inside the PDF.

That gives us a few practical benefits:

The signing secret never needs to be distributed to clients.
There is no certificate chain, expiration, or renewal process to manage.
The signature is small and easy to store.
Verification can be integrated directly into the invoice page.

The tradeoff is that verification requires Reinvoice to be online. You cannot independently verify the invoice offline with only the PDF. If we ever need offline verification, we would add public-key signatures alongside the current HMAC-based integrity check.

Where the Signature Appears

Every invoice page includes a verification badge:

Signed: This invoice was cryptographically verified by Reinvoice.

When someone clicks “Verify signature,” Reinvoice checks the stored signature against the current invoice data. If the values match, the invoice is shown as authentic and unchanged. If they do not match, the badge changes state and the mismatch is logged for investigation.

Lessons Learned

1. Sign structured data, not rendered PDFs

Our first approach was too close to the PDF generation step. That made verification fragile because small rendering differences could change the final PDF bytes.

Signing the structured invoice payload is more reliable. The invoice data is the source of truth, so that is what we protect.

2. Be explicit about signed fields

The field list matters. If a field affects the invoice total, tax amount, payment expectations, or client-facing record, it should be considered for signing.

We learned this when reviewing fields like discountAmount and shippingAmount. Leaving out financial fields creates gaps where invoice data could change without invalidating the signature.

3. Separate immutable invoice data from changing workflow state

Some fields change naturally after an invoice is sent. Payment status is a good example. An invoice may move from sent to paid without meaning the original invoice was tampered with.

For that reason, the signed payload should focus on the invoice data that should remain stable after sending. Workflow state can be tracked separately in the audit log.

4. Public verification needs rate limits

The verification endpoint is intentionally public because clients receiving invoices by email should not need a Reinvoice account to verify authenticity.

Public does not mean unlimited. The endpoint should still be rate-limited, use non-guessable verification tokens where possible, and avoid exposing sensitive invoice details.

5. Log failures carefully

Verification failures are useful signals. They can reveal tampering attempts, data corruption, serialization bugs, or migration issues.

We log signature mismatches for audit and debugging, but we avoid exposing sensitive details in public responses.

The Full Picture

HMAC signatures are one layer in Reinvoice’s broader invoice integrity system.

Combined with tax calculation, payment tracking, and audit logs, they help freelancers and contractors trust that the invoice they created is the same invoice their client sees later.

For a document tied to income, taxes, and client records, that trust matters.

DEV Community: Reinvoice LLC