Node.js SDK Quickstart

Ship a production-ready extension in minutes using the official TypeScript/Node.js SDK. This guide walks through installation, configuration, and running a local webhook server that already exposes health checks, telemetry, custom data helpers, and secret management.

1. Install the SDK

npm install @kiket/sdk

The package bundles TypeScript types and compiles down to modern JavaScript. Use ts-node, tsx, or your build system of choice.

2. Provide credentials

Set the following environment variables (or pass them directly to the KiketSDK constructor):

Variable	Description
KIKET_WEBHOOK_SECRET	HMAC secret used to verify inbound webhooks (X-Kiket-Signature).
KIKET_WORKSPACE_TOKEN	Workspace token for calling back into the REST API.
KIKET_BASE_URL (optional)	API base URL. Defaults to https://kiket.dev.
KIKET_SDK_TELEMETRY_URL (optional)	Overrides the default /api/v1/ext/telemetry endpoint if you want to fan out telemetry to another service.
KIKET_SDK_TELEMETRY_OPTOUT=1 (optional)	Disable telemetry entirely.

Secrets declared in your manifest (settings[].secret: true) can be injected via environment variables named KIKET_SECRET_<SETTING_KEY> (e.g., KIKET_SECRET_API_TOKEN). The SDK automatically merges them into context.settings.

3. Register handlers

import { KiketSDK } from '@kiket/sdk';

const sdk = new KiketSDK({
  // All fields are optional if environment variables + manifest are present.
  webhookSecret: process.env.KIKET_WEBHOOK_SECRET,
  workspaceToken: process.env.KIKET_WORKSPACE_TOKEN,
  extensionId: 'com.example.marketing',
  extensionVersion: '1.0.0',
});

sdk.webhook('issue.created', 'v1')(async (payload, context) => {
  const summary = payload.issue.title;

  await context.endpoints.logEvent('issue.created', { summary });
  await context.secrets.set('WEBHOOK_TOKEN', 'abc123');

  return { ok: true };
});

sdk.webhook('workflow.sla_status', 'v1')(async (payload, context) => {
  const events = await context.endpoints
    .slaEvents(payload.issue.project_id)
    .list({ state: 'imminent', limit: 5 });

  if (!events.data.length) return { ok: true };

  await context.endpoints.notify(
    'SLA warning',
    `Issue #${events.data[0].issue_id} is ${events.data[0].state}`,
    'warning'
  );

  return { acknowledged: true };
});

Handlers are version-aware. The dispatcher requires either a version query parameter, the X-Kiket-Event-Version header, or the /v/{version}/webhooks/{event} path.

4. Run locally

sdk.run('127.0.0.1', 8080);

Use ngrok/cloudflared to expose your local server, or deploy the same Express app anywhere Node.js 18+ is available (Cloud Run, Lambda, Fly.io, etc.).

The SDK automatically serves:

• /webhooks/{event} and /v/{version}/webhooks/{event}
• /health reporting status, registered events, and versions

5. Telemetry & feedback

Every invocation emits telemetry to /api/v1/ext/telemetry (unless opted out). Extend or inspect the payload with a feedback hook:

import { TelemetryRecord } from '@kiket/sdk';

const sdk = new KiketSDK({
  feedbackHook: async (record: TelemetryRecord) => {
    console.log(`[telemetry] ${record.event} -> ${record.status}`);
  },
});

Telemetry includes duration, status, event/version metadata, error information, and any custom metadata you pass when calling sdk.telemetry.record(...).

6. Add a setup wizard (optional)

Guide users through extension configuration with a setup wizard. Add a setup section to your manifest:

.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:
    SLACK_WEBHOOK_URL:
      type: string
      secret: true
      required: true
      label: Slack Webhook URL
    notify_on_sla:
      type: boolean
      default: "true"
      label: Notify on SLA breaches

  setup:
    - secrets:
        id: slack-config
        title: Connect Slack
        description: Enter your Slack webhook URL for notifications
        collect:
          - SLACK_WEBHOOK_URL
    - configure:
        id: preferences
        title: Notification Preferences
        collect:
          - notify_on_sla
    - test:
        id: verify
        title: Test Connection
        endpoint: /test-slack

See the Setup Wizard Guide for all step types.

7. Next steps

• Dive into the Node.js SDK API reference for details on HandlerContext, endpoint helpers, custom data/SLA clients, and the telemetry reporter.
• Explore the deployment cookbook for recipes covering GitHub Actions, Cloud Run, manifest-driven CI, and the kiket extensions CLI integration.