stellar-sdk/com.soneso.stellar.sdk.sep.sep12/PutCustomerCallbackRequest

PutCustomerCallbackRequest

data class PutCustomerCallbackRequest(val jwt: String, val url: String, val id: String? = null, val account: String? = null, val memo: String? = null)

Request for registering a callback URL to receive KYC status updates from a SEP-12 anchor.

Allows clients to receive webhook notifications when customer KYC status changes. The anchor will POST updates to the provided URL. This replaces any previously registered callback URL for the account.

Callback payload format:

The anchor will POST JSON with customer status updates
Callbacks include Signature and X-Stellar-Signature headers for verification
Verify signatures using CallbackSignatureVerifier

Customer identification:

Use id if you have a customer ID from previous registration
Use JWT sub value for account identification (recommended)
Use account and memo for backwards compatibility

Example - Register callback for customer:

val request = PutCustomerCallbackRequest(
    jwt = authToken,
    url = "https://myapp.com/webhooks/kyc-status",
    id = customerId
)

kycService.putCustomerCallback(request)
println("Callback registered, will receive updates at ${request.url}")

Example - Callback for shared account:

val request = PutCustomerCallbackRequest(
    jwt = authToken,
    url = "https://myapp.com/webhooks/kyc-status",
    account = sharedAccountId,
    memo = "user_12345"
)

kycService.putCustomerCallback(request)

Example - Handle callback in server:

// Your webhook endpoint
post("/webhooks/kyc-status") {
    val signatureHeader = call.request.header("Signature")
        ?: call.request.header("X-Stellar-Signature")
    val requestBody = call.receiveText()

    // Verify signature
    if (signatureHeader != null) {
        val isValid = CallbackSignatureVerifier.verify(
            signatureHeader = signatureHeader,
            requestBody = requestBody,
            expectedHost = "myapp.com",
            anchorSigningKey = anchorPublicKey
        )

        if (isValid) {
            // Parse and process status update
            val update = Json.decodeFromString<GetCustomerInfoResponse>(requestBody)
            handleStatusUpdate(update)
            call.respond(HttpStatusCode.OK)
        } else {
            call.respond(HttpStatusCode.Unauthorized, "Invalid signature")
        }
    }
}