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.
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:
- Project detail → paste secret → Send success/fail callback to your apiUrl.
- Or use /demo with apiUrl = https://sdk.perper.net/api/demo/callback and inspect /demo/callbacks. /demo · /demo/callbacks
- 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)