Skip to content

Build Your First Extension

Extensions let you run custom automation anywhere while interacting with Kiket through secure APIs and events. This quickstart creates a webhook service that posts Slack notifications when high-priority issues appear.

1. Generate a Manifest

Create .kiket/manifest.yaml in your repository:

model_version: "1.0"
extension:
  id: com.example.slack-notifier
  name: Slack Notifier
  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
      description: Incoming webhook for Slack channel

hooks:
  - issue.created

permissions:
  - read:issues
  - read:projects

Commit and push. During the next sync Kiket validates the manifest and exposes it in the Extensions UI.

2. Register the Extension

  1. Visit Project → Extensions → Add Extension.
  2. Pick the manifest that just synced and click Install.
  3. Provide the Slack webhook URL. The value is stored encrypted.

3. Build the Endpoint

Use the Kiket SDK for your language. Here's a Ruby example:

require 'kiket_sdk'
require 'net/http'
require 'json'

sdk = KiketSDK.new

sdk.webhook('issue.created', version: 'v1') do |payload, context|
  issue = payload['issue']

  # Skip non-high priority issues
  next { ok: true } unless issue['priority'] == 'high'

  # Get Slack webhook URL (per-org config with ENV fallback)
  slack_url = context[:secret].call('SLACK_WEBHOOK_URL')

  # Post to Slack
  uri = URI(slack_url)
  Net::HTTP.post(
    uri,
    { text: "High priority issue created: #{issue['title']} (#{issue['url']})" }.to_json,
    'Content-Type' => 'application/json'
  )

  { ok: true }
end

sdk.run!(port: 9292)

Python Version

from kiket_sdk import KiketSDK
import httpx

sdk = KiketSDK()

@sdk.webhook("issue.created", version="v1")
def handle_issue_created(payload, context):
    issue = payload.get("issue", {})

    # Skip non-high priority issues
    if issue.get("priority") != "high":
        return {"ok": True}

    # Get Slack webhook URL (per-org config with ENV fallback)
    slack_url = context.secret("SLACK_WEBHOOK_URL")

    # Post to Slack
    httpx.post(slack_url, json={
        "text": f"High priority issue created: {issue['title']} ({issue['url']})"
    })

    return {"ok": True}

if __name__ == "__main__":
    sdk.run(port=9292)

Deploy anywhere you like (Cloud Run, Vercel, Fly.io). The SDK handles signature verification, authentication, and telemetry automatically.

4. Subscribe to Events

When the extension is installed Kiket sends events defined in the manifest. Confirm delivery in Project → Extensions → Activity. Retries follow exponential backoff and signatures use HMAC with the project's extension secret.

5. Iterate

  • Add additional handlers (e.g., issue.transitioned)
  • Use context[:endpoints] to comment back on issues or update metadata
  • Use context[:secret].call('KEY') for multi-tenant secret access
  • Package the extension for other teams by publishing to the marketplace (see Extensions → Publishing)

SDK Benefits

Using the SDK provides:

Feature SDK Manual
Signature verification Automatic Manual HMAC
Runtime tokens Automatic Manual extraction
Secret resolution Multi-tenant + ENV fallback ENV only
Telemetry Automatic None
Error handling Standardized Custom

Next Steps

You have now shipped your first extension and connected external tooling to Kiket's workflow engine.