Add E-Signatures to Kotlin & Ktor Backend Services via REST API (2026)

plugins {
    kotlin("jvm") version "2.1.0"
    kotlin("plugin.serialization") version "2.1.0"
    id("io.ktor.plugin") version "3.0.3"
}

group = "com.acme.contracts"
version = "1.0.0"

application {
    mainClass.set("com.acme.contracts.ApplicationKt")
}

repositories {
    mavenCentral()
}

val ktorVersion = "3.0.3"
val exposedVersion = "0.58.0"
val coroutinesVersion = "1.10.1"

dependencies {
    // Ktor 3 Server Core & Netty/CIO Engine
    implementation("io.ktor:ktor-server-core-jvm:$ktorVersion")
    implementation("io.ktor:ktor-server-cio-jvm:$ktorVersion")
    implementation("io.ktor:ktor-server-content-negotiation-jvm:$ktorVersion")
    implementation("io.ktor:ktor-server-status-pages-jvm:$ktorVersion")
    implementation("io.ktor:ktor-server-call-id-jvm:$ktorVersion")

    // Ktor 3 Non-Blocking HttpClient for Signbee REST API
    implementation("io.ktor:ktor-client-core-jvm:$ktorVersion")
    implementation("io.ktor:ktor-client-cio-jvm:$ktorVersion")
    implementation("io.ktor:ktor-client-content-negotiation-jvm:$ktorVersion")
    implementation("io.ktor:ktor-client-logging-jvm:$ktorVersion")

    // Compile-Time JSON Serialization (Zero Reflection)
    implementation("io.ktor:ktor-serialization-kotlinx-json-jvm:$ktorVersion")
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:$coroutinesVersion")

    // JetBrains Exposed ORM & HikariCP for Contract Audit Persistence
    implementation("org.jetbrains.exposed:exposed-core:$exposedVersion")
    implementation("org.jetbrains.exposed:exposed-jdbc:$exposedVersion")
    implementation("org.jetbrains.exposed:exposed-java-time:$exposedVersion")
    implementation("com.zaxxer:HikariCP:6.2.1")
    implementation("org.postgresql:postgresql:42.7.4")

    // Structured Logging
    implementation("ch.qos.logback:logback-classic:1.5.12")
    testImplementation("io.ktor:ktor-server-test-host-jvm:$ktorVersion")
    testImplementation("io.ktor:ktor-client-mock-jvm:$ktorVersion")
    testImplementation(kotlin("test"))
}

package com.acme.contracts.signbee

import io.ktor.client.*
import io.ktor.client.call.*
import io.ktor.client.engine.cio.*
import io.ktor.client.plugins.*
import io.ktor.client.plugins.contentnegotiation.*
import io.ktor.client.request.*
import io.ktor.client.statement.*
import io.ktor.http.*
import io.ktor.serialization.kotlinx.json.*
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json

@Serializable
data class SendDocumentRequest(
    val title: String,
    val markdown: String? = null,
    @SerialName("pdf_base64") val pdfBase64: String? = null,
    @SerialName("pdf_url") val pdfUrl: String? = null,
    @SerialName("sender_name") val senderName: String,
    @SerialName("sender_email") val senderEmail: String,
    @SerialName("recipient_name") val recipientName: String,
    @SerialName("recipient_email") val recipientEmail: String,
    @SerialName("expires_in_days") val expiresInDays: Int = 14,
    @SerialName("webhook_url") val webhookUrl: String? = null,
    @SerialName("redirect_url") val redirectUrl: String? = null,
    val metadata: Map<String, String> = emptyMap()
) {
    init {
        val sources = listOfNotNull(markdown, pdfBase64, pdfUrl)
        require(sources.size == 1) {
            "Exactly one of markdown, pdfBase64, or pdfUrl must be provided."
        }
        require(expiresInDays in 1..90) {
            "expiresInDays must be between 1 and 90 days."
        }
    }
}

@Serializable
data class SendDocumentResponse(
    val id: String,
    val status: String,
    val title: String,
    @SerialName("signing_url") val signingUrl: String,
    @SerialName("verify_url") val verifyUrl: String,
    @SerialName("expires_at") val expiresAt: String,
    @SerialName("created_at") val createdAt: String
)

@Serializable
data class SignbeeErrorResponse(
    val error: String,
    val code: String? = null,
    val details: String? = null
)

class SignbeeApiException(
    val statusCode: Int,
    override val message: String,
    val errorCode: String? = null
) : RuntimeException("Signbee API HTTP $statusCode (${errorCode ?: "ERR"}): $message")

class SignbeeClient(
    private val apiKey: String,
    private val baseUrl: String = "https://signb.ee",
    private val httpClient: HttpClient = createDefaultHttpClient(apiKey, baseUrl)
) : AutoCloseable {

    suspend fun sendDocument(
        request: SendDocumentRequest,
        idempotencyKey: String? = null
    ): SendDocumentResponse {
        val response: HttpResponse = httpClient.post("/api/v1/send") {
            contentType(ContentType.Application.Json)
            if (!idempotencyKey.isNullOrBlank()) {
                header("Idempotency-Key", idempotencyKey)
            }
            setBody(request)
        }

        if (!response.status.isSuccess()) {
            val err = runCatching { response.body<SignbeeErrorResponse>() }.getOrNull()
            throw SignbeeApiException(
                statusCode = response.status.value,
                message = err?.error ?: response.bodyAsText(),
                errorCode = err?.code
            )
        }

        return response.body()
    }

    suspend fun getDocumentStatus(documentId: String): SendDocumentResponse {
        val response: HttpResponse = httpClient.get("/api/v1/documents/$documentId")
        if (!response.status.isSuccess()) {
            throw SignbeeApiException(
                statusCode = response.status.value,
                message = response.bodyAsText()
            )
        }
        return response.body()
    }

    override fun close() {
        httpClient.close()
    }

    companion object {
        fun createDefaultHttpClient(apiKey: String, baseUrl: String): HttpClient =
            HttpClient(CIO) {
                engine {
                    maxConnectionsCount = 256
                    endpoint {
                        maxConnectionsPerRoute = 64
                        keepAliveTime = 30_000
                        connectTimeout = 5_000
                        connectAttempts = 2
                    }
                }
                install(ContentNegotiation) {
                    json(
                        Json {
                            ignoreUnknownKeys = true
                            explicitNulls = false
                            encodeDefaults = true
                        }
                    )
                }
                install(HttpTimeout) {
                    requestTimeoutMillis = 15_000
                    connectTimeoutMillis = 5_000
                    socketTimeoutMillis = 15_000
                }
                install(HttpRequestRetry) {
                    retryOnServerErrors(maxRetries = 3)
                    exponentialDelay(base = 2.0, maxDelayMs = 4_000)
                }
                defaultRequest {
                    url(baseUrl)
                    header(HttpHeaders.Authorization, "Bearer $apiKey")
                    header(HttpHeaders.Accept, ContentType.Application.Json)
                }
            }
    }
}

package com.acme.contracts.routes

import io.ktor.http.*
import io.ktor.server.application.*
import io.ktor.server.request.*
import io.ktor.server.response.*
import io.ktor.server.routing.*
import kotlinx.coroutines.Dispatchers
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
import kotlinx.serialization.json.Json
import org.jetbrains.exposed.sql.*
import org.jetbrains.exposed.sql.javatime.timestamp
import org.jetbrains.exposed.sql.transactions.experimental.newSuspendedTransaction
import java.security.MessageDigest
import java.time.Instant
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec

object ContractsTable : Table("contracts") {
    val id = varchar("id", 64)
    val customerId = varchar("customer_id", 64).index()
    val signbeeDocId = varchar("signbee_doc_id", 64).uniqueIndex()
    val status = varchar("status", 32)
    val sha256Hash = varchar("sha256_hash", 128).nullable()
    val signedPdfUrl = text("signed_pdf_url").nullable()
    val verifyUrl = text("verify_url").nullable()
    val signerIp = varchar("signer_ip", 64).nullable()
    val signedAt = timestamp("signed_at").nullable()
    val updatedAt = timestamp("updated_at")
    override val primaryKey = PrimaryKey(id)
}

@Serializable
data class SignbeeWebhookEvent(
    @SerialName("event_id") val eventId: String,
    val event: String, // "document.signed" | "document.declined" | "document.viewed" | "document.expired"
    @SerialName("document_id") val documentId: String,
    val status: String,
    @SerialName("sha256_hash") val sha256Hash: String? = null,
    @SerialName("signed_pdf_url") val signedPdfUrl: String? = null,
    @SerialName("verify_url") val verifyUrl: String? = null,
    @SerialName("signer_ip") val signerIp: String? = null,
    @SerialName("signed_at") val signedAt: String? = null,
    val metadata: Map<String, String> = emptyMap()
)

object SignbeeWebhookVerifier {
    private const val HMAC_ALGO = "HmacSHA256"

    @OptIn(ExperimentalStdlibApi::class)
    fun verifySignature(rawBody: String, signatureHeader: String?, webhookSecret: String): Boolean {
        if (signatureHeader.isNullOrBlank()) return false
        val cleanSig = signatureHeader.removePrefix("sha256=").trim().lowercase()

        val mac = Mac.getInstance(HMAC_ALGO).apply {
            init(SecretKeySpec(webhookSecret.toByteArray(Charsets.UTF_8), HMAC_ALGO))
        }
        val computedBytes = mac.doFinal(rawBody.toByteArray(Charsets.UTF_8))
        val computedHex = computedBytes.toHexString(HexFormat.Default)

        return MessageDigest.isEqual(
            computedHex.toByteArray(Charsets.UTF_8),
            cleanSig.toByteArray(Charsets.UTF_8)
        )
    }
}

private val webhookJson = Json {
    ignoreUnknownKeys = true
    explicitNulls = false
}

fun Route.signbeeWebhookRoutes(webhookSecret: String) {
    post("/webhooks/signbee") {
        val signatureHeader = call.request.header("X-Signbee-Signature")
        val rawPayload = call.receiveText()

        if (!SignbeeWebhookVerifier.verifySignature(rawPayload, signatureHeader, webhookSecret)) {
            call.application.environment.log.warn("Rejected invalid X-Signbee-Signature on webhook")
            call.respond(HttpStatusCode.Unauthorized, mapOf("error" to "Invalid HMAC-SHA256 signature"))
            return@post
        }

        val payload = webhookJson.decodeFromString<SignbeeWebhookEvent>(rawPayload)

        val updatedRows = newSuspendedTransaction(Dispatchers.IO) {
            ContractsTable.update({
                (ContractsTable.signbeeDocId eq payload.documentId) and
                    (ContractsTable.status neq "SIGNED")
            }) { row ->
                row[status] = payload.status.uppercase()
                row[sha256Hash] = payload.sha256Hash
                row[signedPdfUrl] = payload.signedPdfUrl
                row[verifyUrl] = payload.verifyUrl
                row[signerIp] = payload.signerIp
                row[signedAt] = payload.signedAt?.let { Instant.parse(it) }
                row[updatedAt] = Instant.now()
            }
        }

        call.application.environment.log.info(
            "Processed Signbee webhook event=${payload.event} doc=${payload.documentId} updatedRows=$updatedRows"
        )
        call.respond(HttpStatusCode.OK, mapOf("received" to true, "idempotent_update" to (updatedRows > 0)))
    }
}