Build signatures into your own software

curl https://api.kovapdf.com/api/v1/sign-requests \
  -H "Authorization: Bearer kova_test_YOUR_KEY" \
  -H "Idempotency-Key: 6f1c2a8e-3d4b-4f7a-9a51-2b8f0c9e7d13" \
  -F "file=@lease.pdf" \
  -F 'spec={
    "title": "Lease agreement",
    "sequential": false,
    "expiresInDays": 14,
    "signers": [{ "name": "Emily Carter", "email": "emily@example.com", "order": 1 }],
    "fields": [{ "signer": 0, "kind": "SIGNATURE", "page": 1, "x": 72, "y": 90, "width": 180, "height": 48 }]
  }'

import { readFile } from "node:fs/promises";
import { randomUUID } from "node:crypto";

// Store this with your own record, and send the same one again on a retry.
const idempotencyKey = randomUUID();

const form = new FormData();
form.append("file", new Blob([await readFile("lease.pdf")], { type: "application/pdf" }), "lease.pdf");
form.append("spec", JSON.stringify({
  title: "Lease agreement",
  sequential: false,
  expiresInDays: 14,
  signers: [{ name: "Emily Carter", email: "emily@example.com", order: 1 }],
  fields: [{ signer: 0, kind: "SIGNATURE", page: 1, x: 72, y: 90, width: 180, height: 48 }],
}));

const res = await fetch("https://api.kovapdf.com/api/v1/sign-requests", {
  method: "POST",
  headers: { Authorization: "Bearer kova_test_YOUR_KEY", "Idempotency-Key": idempotencyKey },
  body: form,
});
const request = await res.json();
console.log(res.status, res.headers.get("KovaPDF-Test-Tasks-Left"), request.id, request.status);

import json, uuid
import requests

# Store this with your own record, and send the same one again on a retry.
idempotency_key = str(uuid.uuid4())

spec = {
    "title": "Lease agreement",
    "sequential": False,
    "expiresInDays": 14,
    "signers": [{"name": "Emily Carter", "email": "emily@example.com", "order": 1}],
    "fields": [{"signer": 0, "kind": "SIGNATURE", "page": 1, "x": 72, "y": 90, "width": 180, "height": 48}],
}

with open("lease.pdf", "rb") as pdf:
    res = requests.post(
        "https://api.kovapdf.com/api/v1/sign-requests",
        headers={"Authorization": "Bearer kova_test_YOUR_KEY", "Idempotency-Key": idempotency_key},
        files={"file": ("lease.pdf", pdf, "application/pdf")},
        data={"spec": json.dumps(spec)},
    )

request = res.json()
print(res.status_code, res.headers.get("KovaPDF-Test-Tasks-Left"), request["id"], request["status"])

<?php
// Store this with your own record, and send the same one again on a retry.
$idempotencyKey = bin2hex(random_bytes(16));

$spec = [
    "title" => "Lease agreement",
    "sequential" => false,
    "expiresInDays" => 14,
    "signers" => [["name" => "Emily Carter", "email" => "emily@example.com", "order" => 1]],
    "fields" => [["signer" => 0, "kind" => "SIGNATURE", "page" => 1, "x" => 72, "y" => 90, "width" => 180, "height" => 48]],
];

$ch = curl_init("https://api.kovapdf.com/api/v1/sign-requests");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer kova_test_YOUR_KEY", "Idempotency-Key: $idempotencyKey"],
    CURLOPT_POSTFIELDS => [
        "file" => new CURLFile("lease.pdf", "application/pdf"),
        "spec" => json_encode($spec),
    ],
]);
$request = json_decode(curl_exec($ch), true);
echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), " ", $request["id"], " ", $request["status"], PHP_EOL;

# Check a delivery by hand: the raw body saved as body.json,
# and the t= value from its KovaPDF-Signature header.
t=1790000000
{ printf '%s.' "$t"; cat body.json; } \
  | openssl dgst -sha256 -hmac "$KOVAPDF_WEBHOOK_SECRET" \
  | awk '{ print $NF }'
# The result must equal the v1= value of the header.

import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.KOVAPDF_WEBHOOK_SECRET; // whsec_...

function verifyKovaSignature(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds || !parts.v1) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return expected.length === parts.v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

const app = express();
app.post("/kovapdf/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verifyKovaSignature(raw, req.get("KovaPDF-Signature") ?? "", SECRET)) return res.sendStatus(400);
  const event = JSON.parse(raw);
  if (event.type === "request.completed") {
    // Download the signed PDF: GET /sign-requests/{id}/document?version=final
  }
  res.sendStatus(200);
});
app.listen(3000);

import hashlib, hmac, os, time
from flask import Flask, request, abort

SECRET = os.environ["KOVAPDF_WEBHOOK_SECRET"]  # whsec_...

def verify_kova_signature(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    try:
        parts = dict(p.split("=", 1) for p in header.split(","))
        t = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - t) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

app = Flask(__name__)

@app.post("/kovapdf/webhook")
def kovapdf_webhook():
    raw = request.get_data()  # raw bytes, before parsing
    if not verify_kova_signature(raw, request.headers.get("KovaPDF-Signature", ""), SECRET):
        abort(400)
    event = request.get_json()
    if event["type"] == "request.completed":
        pass  # download the signed PDF
    return "", 200

<?php
$secret = getenv("KOVAPDF_WEBHOOK_SECRET"); // whsec_...
$raw = file_get_contents("php://input");    // raw body, before parsing
$header = $_SERVER["HTTP_KOVAPDF_SIGNATURE"] ?? "";

$parts = [];
foreach (explode(",", $header) as $part) {
    [$k, $v] = array_pad(explode("=", $part, 2), 2, "");
    $parts[$k] = $v;
}
$t = (int) ($parts["t"] ?? 0);
$expected = hash_hmac("sha256", $t . "." . $raw, $secret);

if (abs(time() - $t) > 300 || !hash_equals($expected, $parts["v1"] ?? "")) {
    http_response_code(400);
    exit;
}

$event = json_decode($raw, true);
if ($event["type"] === "request.completed") {
    // Download the signed PDF
}
http_response_code(200);

curl -o lease-signed.pdf "https://api.kovapdf.com/api/v1/sign-requests/$REQUEST_ID/document?version=final" \
  -H "Authorization: Bearer kova_test_YOUR_KEY"

import { writeFile } from "node:fs/promises";

const res = await fetch(`https://api.kovapdf.com/api/v1/sign-requests/${requestId}/document?version=final`, {
  headers: { Authorization: "Bearer kova_test_YOUR_KEY" },
});
if (!res.ok) throw new Error((await res.json()).code); // NO_FINAL until everyone has signed
await writeFile("lease-signed.pdf", Buffer.from(await res.arrayBuffer()));

import requests

res = requests.get(
    f"https://api.kovapdf.com/api/v1/sign-requests/{request_id}/document",
    params={"version": "final"},
    headers={"Authorization": "Bearer kova_test_YOUR_KEY"},
)
res.raise_for_status()  # 404 NO_FINAL until everyone has signed
with open("lease-signed.pdf", "wb") as out:
    out.write(res.content)

<?php
$ch = curl_init("https://api.kovapdf.com/api/v1/sign-requests/$requestId/document?version=final");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer kova_test_YOUR_KEY"],
]);
$pdf = curl_exec($ch);
if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) === 200) {
    file_put_contents("lease-signed.pdf", $pdf);
}

curl https://api.kovapdf.com/api/v1/verify \
  -H "Authorization: Bearer kova_test_YOUR_KEY" \
  -H "Idempotency-Key: 0d3f5b8a-6c2e-4e1b-8f47-91a3c5d7e2b6" \
  -F "file=@signed.pdf"

import { readFile } from "node:fs/promises";
import { randomUUID } from "node:crypto";

const form = new FormData();
form.append("file", new Blob([await readFile("signed.pdf")], { type: "application/pdf" }), "signed.pdf");

const res = await fetch("https://api.kovapdf.com/api/v1/verify", {
  method: "POST",
  headers: { Authorization: "Bearer kova_test_YOUR_KEY", "Idempotency-Key": randomUUID() },
  body: form,
});
const report = await res.json();
for (const s of report.signatures) console.log(s.verdict, s.status.certificate);

import uuid
import requests

with open("signed.pdf", "rb") as pdf:
    res = requests.post(
        "https://api.kovapdf.com/api/v1/verify",
        headers={"Authorization": "Bearer kova_test_YOUR_KEY", "Idempotency-Key": str(uuid.uuid4())},
        files={"file": ("signed.pdf", pdf, "application/pdf")},
    )

for sig in res.json()["signatures"]:
    print(sig["verdict"], sig["status"]["certificate"])

<?php
$ch = curl_init("https://api.kovapdf.com/api/v1/verify");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer kova_test_YOUR_KEY", "Idempotency-Key: " . bin2hex(random_bytes(16))],
    CURLOPT_POSTFIELDS => ["file" => new CURLFile("signed.pdf", "application/pdf")],
]);
$report = json_decode(curl_exec($ch), true);
foreach ($report["signatures"] as $sig) {
    echo $sig["verdict"], " ", $sig["status"]["certificate"], PHP_EOL;
}

curl https://api.kovapdf.com/api/v1/digital-sign \
  -H "Authorization: Bearer kova_test_YOUR_KEY" \
  -H "Idempotency-Key: 9b2d4f6a-1c3e-4a5b-8d7f-0e2c4a6b8d1f" \
  -F "file=@contract.pdf" \
  -F "certificate=@company.pfx" \
  -F "password=$PFX_PASSWORD" \
  -F "reason=Approved" -F "location=London" \
  -o contract-signed.pdf -D -

import { readFile, writeFile } from "node:fs/promises";
import { randomUUID } from "node:crypto";

const form = new FormData();
form.append("file", new Blob([await readFile("contract.pdf")]), "contract.pdf");
form.append("certificate", new Blob([await readFile("company.pfx")]), "company.pfx");
form.append("password", process.env.PFX_PASSWORD);
form.append("reason", "Approved");

const res = await fetch("https://api.kovapdf.com/api/v1/digital-sign", {
  method: "POST",
  headers: { Authorization: "Bearer kova_test_YOUR_KEY", "Idempotency-Key": randomUUID() },
  body: form,
});
if (!res.ok) throw new Error((await res.json()).code); // for example WRONG_PASSWORD
console.log(res.headers.get("X-Signature-Profile"));
await writeFile("contract-signed.pdf", Buffer.from(await res.arrayBuffer()));

import os, uuid
import requests

with open("contract.pdf", "rb") as pdf, open("company.pfx", "rb") as pfx:
    res = requests.post(
        "https://api.kovapdf.com/api/v1/digital-sign",
        headers={"Authorization": "Bearer kova_test_YOUR_KEY", "Idempotency-Key": str(uuid.uuid4())},
        files={"file": ("contract.pdf", pdf, "application/pdf"), "certificate": ("company.pfx", pfx)},
        data={"password": os.environ["PFX_PASSWORD"], "reason": "Approved"},
    )

res.raise_for_status()  # 400 WRONG_PASSWORD, CERTIFICATE_EXPIRED, ...
print(res.headers["X-Signature-Profile"])
with open("contract-signed.pdf", "wb") as out:
    out.write(res.content)

<?php
$ch = curl_init("https://api.kovapdf.com/api/v1/digital-sign");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer kova_test_YOUR_KEY", "Idempotency-Key: " . bin2hex(random_bytes(16))],
    CURLOPT_POSTFIELDS => [
        "file" => new CURLFile("contract.pdf", "application/pdf"),
        "certificate" => new CURLFile("company.pfx"),
        "password" => getenv("PFX_PASSWORD"),
        "reason" => "Approved",
    ],
]);
$pdf = curl_exec($ch);
if (curl_getinfo($ch, CURLINFO_RESPONSE_CODE) === 200) {
    file_put_contents("contract-signed.pdf", $pdf);
}