Skip to content

Webhooks

Prove each payment notification came from Perper before you fulfill. This is the merchant trust surface (Stripe: Verify signatures).

Why this exists

Anyone can open a fake success URL in a browser. Your apiUrl must cryptographically check that Perper signed the opaque order data with your project secret. Only then mark the order paid.

Callback contract (apiUrl POST)

JSON body fields:

  • status — success | fail
  • data — opaque string you sent on /pay (e.g. order id)
  • hash — HS256 JWT of that data string, signed with the project secret
  • transactionId — present on success when the ledger transfer completed
  • customId — echoed when you supplied it on /pay or Contabo QR

Verify the hash (required)

Backend signs with jwt.sign(dataString, projectSecret) (HS256). Mirror that on your server. If verification fails, respond 400 and do not fulfill.

Pin algorithms: ['HS256']. Reject alg=none / RS*. Wrong secret → invalid signature.

javascript
const jwt = require("jsonwebtoken");

/** Same as Perper backend generateHash — HS256 of opaque data string */
function verifyPayHash({ data, hash, secret }) {
  const payload = jwt.verify(hash, secret, { algorithms: ["HS256"] });
  if (payload !== data) throw new Error("mismatch");
  return data;
}

// apiUrl POST body: { status, data, hash, transactionId?, customId? }
app.post("/perper/webhook", (req, res) => {
  const { status, data, hash, transactionId } = req.body;
  try {
    verifyPayHash({
      data,
      hash,
      secret: process.env.PERPER_PROJECT_SECRET,
    });
  } catch {
    return res.sendStatus(400); // never fulfill
  }
  // de-dupe on transactionId || data, then fulfill once
  res.sendStatus(200);
});

Idempotency

Contabo currently POSTs each success webhook once (single fetch). Still de-dupe on transactionId when present, else on opaque data / customId — a duplicate post must not double-fulfill.

Two hash contracts

Pay callback / redirect hash = JWT of the opaque data string alone. checkStatus hash = JWT of { projectId, customId }. Do not mix the two payloads.

Status vocabulary

Redirect query uses status=success|error. Webhook body uses status=success|fail. Treat error and fail as the same failure class.

Failure modes

Treat these as reject / investigate — never fulfill:

  • Unsigned — data and hash both missing (legacy or misconfigured success path).
  • Invalid / mismatch — tampered data, bad JWT, or algorithms confusion.
  • Wrong secret — JsonWebTokenError invalid signature (rotate or paste the current project secret).

Prove it in the portal (live)

Giants ship Dashboard “Send test webhook”. Perper gives you the same loop without a CLI:

  1. Project detail → paste secret → Send success/fail callback to your apiUrl.
  2. Or use /demo with apiUrl = https://sdk.perper.net/api/demo/callback and inspect /demo/callbacks. /demo · /demo/callbacks
  3. On /demo/callbacks paste the project secret → Verify → badge Verified / Invalid / Unsigned. Secret is never stored.

What “Verified” means

Verified = jwt.verify(hash, secret, { algorithms: ['HS256'] }) returned the same data string. That is your system proof that Perper authored the callback. Invalid / Unsigned means do not fulfill.

Test mode (sk_test_)

Portal-only BFF sandbox: sk_test_ lives in the SDK website store, not the Contabo ledger. Use Send test callback (Test mode) to prove your endpoint — no balance moves. Real pay webhooks are signed with the Contabo project secret. Delivery outcomes appear on the project page (Recent webhook deliveries).

Next: wire this into production checkout, then skim Payments for the hosted /pay URL. Payments · Security (bank-level)