Java SDK

EtchvClient(key, baseUrl, Duration) sets the timeout. The default is 120 seconds. Each call blocks until it finishes. If the thread is interrupted, the call throws InterruptedException. Use new EtchvClient.Options(filename, idempotencyKey) for media requests. Run the examples below inside the open client’s scope.

Errors throw EtchvClient.EtchvException, an unchecked exception. It has statusCode(), requestId(), idempotencyKey() and detail(). Status 0 means no response was received. isGone() tells you the status was HTTP 410.

try {
    var result = client.getEmbedResult(requestId);
} catch (EtchvClient.EtchvException e) {
    if (e.isGone()) {
        // Saved result expired or its asset was deleted; retrying does not charge again.
    }
    log.warn("Etchv failed: status={} requestId={}", e.statusCode(), e.requestId());
}

See HTTP errors and retry behavior. When you report a failure, include the request ID.

var page = client.listAssets(Map.of("kind", "watermarked", "limit", "25"));
for (var item : page.items()) {
    var asset = client.getAsset(item.id());
    var updated = client.updateAsset(asset.id(), asset.version(),
        Map.of("metadata", Map.of("campaign", "spring")));
    if (updated.fileAvailable()) {
        byte[] bytes = client.downloadAsset(updated.id());
    }
}
// Use nextCursor() with the same filters to continue listing.

An edit replaces the metadata and must send the asset's current version. A 409 conflict means the asset changed since you read it, so fetch it again and redo your edit. deleteAsset deletes one asset. deleteAssets deletes 1–50 assets as one action: either all are deleted or none are. Asset fields, filters and retention.

Read the file into memory before you submit it.

var job = client.submitEmbed("documents", pdfBytes, Map.of("delivery", "delivery_001"),
    new EtchvClient.Options("document.pdf", "delivery_001"), webhookId);
String requestId = job.get("request_id").getAsString();
var status = client.getJob(requestId, false);   // queued, running, retrying, succeeded, failed
var result = client.getEmbedResult(requestId);  // waits while the job is pending

The webhook is optional. In Java or Rust, pass null or None to skip it. Save the receipt. Job handling.

Methods: createWebhook, listWebhooks, updateWebhook, deleteWebhook, listWebhookDeliveries, redeliverWebhook. Viewing webhooks needs webhooks:read. Managing them needs webhooks:write and the owner or admin role. The signing secret is shown only once, so save it.

boolean valid = EtchvClient.verifyWebhookSignature(rawBody,
    request.getHeader("X-Etchv-Timestamp"), request.getHeader("X-Etchv-Signature"), signingSecret);
if (!valid) throw new SecurityException("Invalid webhook signature");
// Then check the body id equals X-Etchv-Event-ID, deduplicate, enqueue work, and return 2xx.

verifyWebhookSignature checks the signature and timestamp. Reject an invalid signature. Then check that the event ID in the body matches X-Etchv-Event-ID. Pass the raw request bytes and use a 300-second timestamp tolerance. Then skip events you already handled, queue the work and return 2xx. Verification rules.

var job = client.submitEmbed("documents", pdfBytes,
    Map.of("recipient", "customer-123"),
    new EtchvClient.Options("report.pdf", "report-export-001", destinationId,
        "reports/watermarked.pdf"), null);
// After the watermark job reports succeeded:
var delivery = client.getStorageDelivery(job.get("storage_delivery_id").getAsString());

After the job succeeds, check the delivery with the storage:read scope. Checking before then returns 404. When the status is stored, download the file with downloadStorageDelivery.

retryStorageDelivery retries a failed or cancelled delivery at no cost. It needs storage:write and the owner or admin role. To manage destinations and deliveries, use createStorageDestination, verifyStorageDestination, updateStorageDestination, deleteStorageDestination, createStorageDelivery. See delivery recovery.