Webhook Authentication

Tesser signs every outgoing webhook request with an Ed25519 asymmetric signature. You should verify this signature on your server before processing the payload.

Signature Header

Each webhook request includes the following headers:

The signature is computed over the exact UTF-8 bytes of the JSON request body. Do not parse and re-serialize the body before verifying — use the raw bytes.

Public Keys

Tesser uses separate public keys for production and sandbox. Pick the one that matches the environment the webhook is being delivered from, and reject signatures verified against the wrong key.

Both keys are provided in SPKI DER format, base64-encoded.

If you're using the SDK, import the constants directly:

Code
 
import {
  WEBHOOK_PUBLIC_KEY,
  WEBHOOK_SANDBOX_PUBLIC_KEY,
} from "@tesser-payments/types";

Otherwise, copy the literal values from the table above.

Verifying Signatures

Pass the public key for the environment the webhook is being delivered from — use WEBHOOK_PUBLIC_KEY for production webhooks and WEBHOOK_SANDBOX_PUBLIC_KEY for sandbox / staging webhooks.

Code
 
import { createPublicKey, verify } from "node:crypto";
import {
  WEBHOOK_PUBLIC_KEY,
  WEBHOOK_SANDBOX_PUBLIC_KEY,
} from "@tesser-payments/types";

function verifyWebhook(rawBody, signature, publicKey) {
  const publicKeyObj = createPublicKey({
    key: Buffer.from(publicKey, "base64"),
    type: "spki",
    format: "der",
  });
  return verify(
    null,
    Buffer.from(rawBody, "utf8"),
    publicKeyObj,
    Buffer.from(signature, "base64"),
  );
}

// In your webhook handler — pick the key for the environment you're
// receiving webhooks from (sandbox / staging shown here):
const signature = req.headers["x-tesser-signature"];
if (typeof signature !== "string" || signature.length === 0) {
  return res.status(401).json({ error: "Missing signature" });
}
const isValid = verifyWebhook(
  req.rawBody,
  signature,
  WEBHOOK_SANDBOX_PUBLIC_KEY,
);

if (!isValid) {
  return res.status(401).json({ error: "Invalid signature" });
}

Important Notes

• Always verify using the raw request body bytes. Parsing the JSON and re-serializing may change whitespace or key order, which will invalidate the signature.
• If verification fails, respond with 401 and do not process the event.
• The public key may be rotated in the future. Key rotation will be announced in advance and communicated through the Tesser Dashboard.