Webhooks

POST /webhooks/velpay HTTP/1.1
Content-Type: application/json
User-Agent: velpay/1 (+https://velpay.pro/docs/guides/webhooks)
Velpay-Timestamp: 1793400123
Velpay-Id: evt_9aZ…
Velpay-Event: order.paid
Velpay-Delivery: dlv_…
Velpay-Attempt: 1
Velpay-Signature: key_4fQ9aZk2LmP0=3q0X…base64…Ag==

{"object":"event","id":"evt_9aZ…","type":"order.paid","livemode":true,"created":1793400123,"data":{"object":{"object":"order","id":"ord_…","state":"paid",…}}}

import express from "express";
import { createPublicKey, verify } from "node:crypto";

// VELPAY_PUBLIC_KEY: the base64 key from Developers → Webhooks (32 raw bytes).
const PUBLIC_KEY = createPublicKey({
  key: Buffer.concat([Buffer.from("302a300506032b6570032100", "hex"), Buffer.from(process.env.VELPAY_PUBLIC_KEY, "base64")]),
  format: "der",
  type: "spki",
});

/** rawBody: the request body as a Buffer, exactly as received. */
function verifyVelpay(rawBody, timestamp, eventId, signatures) {
  if (!/^\d+$/.test(timestamp ?? "") || !eventId) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const message = Buffer.concat([Buffer.from(`vp.whk.1\n${timestamp}\n${eventId}\n`), rawBody]);
  // "key_…=<signature>" per signing key (two during a rotation): accept if any verifies.
  return (signatures ?? "").split(",").some((pair) => {
    const eq = pair.indexOf("=");
    return eq > 0 && verify(null, message, PUBLIC_KEY, Buffer.from(pair.slice(eq + 1).trim(), "base64"));
  });
}

const app = express();

// express.raw keeps the bytes; express.json() would re-serialize them and break the signature.
app.post("/webhooks/velpay", express.raw({ type: "application/json" }), async (req, res) => {
  if (!verifyVelpay(req.body, req.get("Velpay-Timestamp"), req.get("Velpay-Id"), req.get("Velpay-Signature"))) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString("utf8"));
  if (await seen(event.id)) return res.sendStatus(200); // already handled
  await queue.add(event);                                // do the work after answering
  res.sendStatus(200);
});

// app/api/webhooks/velpay/route.ts (Next.js App Router)
export async function POST(req: Request) {
  const raw = Buffer.from(await req.arrayBuffer());
  const h = req.headers;
  if (!verifyVelpay(raw, h.get("velpay-timestamp"), h.get("velpay-id"), h.get("velpay-signature"))) {
    return new Response("bad signature", { status: 401 });
  }
  const event = JSON.parse(raw.toString("utf8"));
  // …
  return new Response(null, { status: 200 });
}

<?php
// Needs the sodium extension (bundled with PHP 7.2+).
function verify_velpay(string $rawBody, string $timestamp, string $eventId, string $signatures): bool
{
    if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > 300 || $eventId === '') {
        return false;
    }
    $key = base64_decode((string) getenv('VELPAY_PUBLIC_KEY'), true);
    if ($key === false || strlen($key) !== SODIUM_CRYPTO_SIGN_PUBLICKEYBYTES) {
        return false;
    }
    $message = "vp.whk.1\n" . $timestamp . "\n" . $eventId . "\n" . $rawBody;
    // "key_…=<signature>" per signing key (two during a rotation): accept if any verifies.
    foreach (explode(',', $signatures) as $pair) {
        $eq = strpos($pair, '=');
        $sig = $eq ? base64_decode(trim(substr($pair, $eq + 1)), true) : false;
        if ($sig !== false && strlen($sig) === SODIUM_CRYPTO_SIGN_BYTES
            && sodium_crypto_sign_verify_detached($sig, $message, $key)) {
            return true;
        }
    }
    return false;
}

$raw = file_get_contents('php://input'); // raw bytes, not $_POST
$ok  = verify_velpay(
    $raw,
    $_SERVER['HTTP_VELPAY_TIMESTAMP'] ?? '',
    $_SERVER['HTTP_VELPAY_ID'] ?? '',
    $_SERVER['HTTP_VELPAY_SIGNATURE'] ?? ''
);
if (!$ok) {
    http_response_code(401);
    exit;
}
$event = json_decode($raw, true);
// … dedupe on $event['id'], then handle $event['type']
http_response_code(200);

import base64, os, time

from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
from flask import Flask, request

PUBLIC_KEY = Ed25519PublicKey.from_public_bytes(base64.b64decode(os.environ["VELPAY_PUBLIC_KEY"]))


def verify_velpay(raw_body: bytes, timestamp: str, event_id: str, signatures: str) -> bool:
    if not timestamp or not timestamp.isdigit() or abs(time.time() - int(timestamp)) > 300 or not event_id:
        return False
    message = f"vp.whk.1\n{timestamp}\n{event_id}\n".encode() + raw_body
    # "key_…=<signature>" per signing key (two during a rotation): accept if any verifies.
    for pair in (signatures or "").split(","):
        key_id, eq, sig = pair.strip().partition("=")
        if not key_id or not eq:
            continue
        try:
            PUBLIC_KEY.verify(base64.b64decode(sig, validate=True), message)
            return True
        except (InvalidSignature, ValueError):
            continue
    return False


app = Flask(__name__)


@app.post("/webhooks/velpay")
def velpay_webhook():
    raw = request.get_data()  # bytes as received; don't use request.json here
    h = request.headers
    if not verify_velpay(raw, h.get("Velpay-Timestamp"), h.get("Velpay-Id"), h.get("Velpay-Signature")):
        return "", 401
    event = request.get_json()
    # … dedupe on event["id"], then handle event["type"]
    return "", 200

switch (event.type) {
  case "order.paid":
    // Look the order up by event.data.object.id (or metadata / reference) and fulfil it once.
    await fulfil(event.data.object);
    break;
  case "order.underpaid":
    await flagForReview(event.data.object); // amount_paid < amount
    break;
  case "order.expired":
  case "order.voided":
    await releaseStock(event.data.object);
    break;
  case "refund.sent":
    await markRefunded(event.data.object);  // a refund object: order, amount, tx_hash
    break;
  case "charge.failed":
    // One payment attempt failed; the order usually stays open for another try.
    await noteAttempt(event.data.object.id, event.data.failure_code); // e.g. "expired", "declined"
    break;
  default:
    // New event types can appear at any time. Ignore what you don't know, but answer 2xx.
}

# Cloudflare Tunnel (no account needed for a quick tunnel)
cloudflared tunnel --url http://localhost:3000

# or ngrok
ngrok http 3000