Java SDK Quickstart

Build Spring Boot extensions with the dev.kiket:kiket-sdk artifact. This guide covers installation, configuration, and a minimal webhook server.

1. Install dependency

Maven

<dependency>
  <groupId>dev.kiket</groupId>
  <artifactId>kiket-sdk</artifactId>
  <version>0.1.0</version>
</dependency>

Gradle (Kotlin DSL)

implementation("dev.kiket:kiket-sdk:0.1.0")

2. Configure environment

Variable	Description
KIKET_WEBHOOK_SECRET	HMAC secret for verifying X-Kiket-Signature.
KIKET_WORKSPACE_TOKEN	Workspace token for REST calls.
KIKET_BASE_URL (optional)	Defaults to https://kiket.dev.
KIKET_SDK_TELEMETRY_URL (optional)	Override telemetry target.
KIKET_SDK_TELEMETRY_OPTOUT=1 (optional)	Disable telemetry.
KIKET_SECRET_<KEY>	Provide secret settings declared in the manifest.

3. Register handlers

import dev.kiket.sdk.KiketSDK;

public final class Main {
    public static void main(String[] args) {
        KiketSDK sdk = KiketSDK.builder()
            .webhookSecret(System.getenv("KIKET_WEBHOOK_SECRET"))
            .workspaceToken(System.getenv("KIKET_WORKSPACE_TOKEN"))
            .extensionId("com.example.marketing")
            .extensionVersion("1.0.0")
            .build();

        sdk.register("issue.created", "v1", (payload, context) -> {
            String summary = (String) ((Map<?, ?>) payload.get("issue")).get("title");
            context.getEndpoints().logEvent("issue.created", Map.of("summary", summary));
            context.getSecrets().set("WEBHOOK_TOKEN", UUID.randomUUID().toString());
            return Map.of("ok", true);
        });

        sdk.register("workflow.sla_status", "v1", (payload, context) -> {
            String projectId = String.valueOf(((Map<?, ?>) payload.get("issue")).get("project_id"));
            var events = context.getEndpoints().slaEvents(projectId).list(options -> {
                options.setState("imminent");
                options.setLimit(5);
            });
            return events.getData().isEmpty()
                ? Map.of("ok", true)
                : Map.of("acknowledged", true);
        });

        sdk.run("127.0.0.1", 8080);
    }
}

Handlers can return any JSON-serializable object. Express versions with /v/{version} paths or rely on the X-Kiket-Event-Version header.

4. Telemetry & feedback

sdk = KiketSDK.builder()
    .telemetryEnabled(true)
    .feedbackHook(record -> {
        System.out.printf(
            "[telemetry] %s@%s %s (%sms)%n",
            record.getEvent(),
            record.getVersion(),
            record.getStatus(),
            record.getDurationMs()
        );
    })
    .build();

Telemetry is POSTed to /api/v1/ext/telemetry using the runtime token from webhook payloads. Set KIKET_SDK_TELEMETRY_OPTOUT=1 to disable.

5. Add a setup wizard (optional)

Define a setup wizard in your manifest to guide users through configuration:

.kiket/extension.yaml

model_version: "1.0"
extension:
  id: com.example.marketing
  name: Marketing Automation
  version: 1.0.0
  delivery: http
  callback:
    url: ${EXTENSION_BASE_URL}
    secret: env.KIKET_WEBHOOK_SECRET

  configuration:
    MAILCHIMP_API_KEY:
      type: string
      secret: true
      required: true
      label: Mailchimp API Key
    list_id:
      type: string
      required: true
      label: Default List ID

  setup:
    - secrets:
        id: mailchimp
        title: Connect Mailchimp
        description: Enter your Mailchimp API credentials
        collect:
          - MAILCHIMP_API_KEY
    - configure:
        id: lists
        title: Configure Lists
        collect:
          - list_id
    - test:
        id: verify
        title: Verify Connection
        endpoint: /test-mailchimp

See the Setup Wizard Guide for all step types.

6. Next steps

• Review the API reference for details on HandlerContext, endpoint helpers, and telemetry payloads.
• Use the deployment cookbook for container guidance, CLI automation, and observability patterns.