Ruby SDK Quickstart¶

Spin up a Sinatra-based extension with battle-tested helpers for secrets, telemetry, custom data, and SLA monitoring.

1. Install¶

gem install kiket-sdk

The gem targets Ruby 3.2+ and ships with Sorbet signatures for better tooling support.

2. Configure environment¶

Variable	Purpose
`KIKET_WEBHOOK_SECRET`	Verifies inbound payloads (`X-Kiket-Signature`).
`KIKET_WORKSPACE_TOKEN`	Authenticates outbound REST calls.
`KIKET_BASE_URL` (optional)	Defaults to `https://kiket.dev`. Override for staging.
`KIKET_SDK_TELEMETRY_URL` (optional)	Mirror telemetry to another endpoint.
`KIKET_SDK_TELEMETRY_OPTOUT=1` (optional)	Disables telemetry entirely.
`KIKET_SECRET_<KEY>`	Inject manifest secrets such as `API_TOKEN`.

3. Register handlers¶

require 'kiket_sdk'

sdk = KiketSDK.new(
  webhook_secret: ENV['KIKET_WEBHOOK_SECRET'],
  workspace_token: ENV['KIKET_WORKSPACE_TOKEN']
)

sdk.webhook('issue.created', version: 'v1') do |payload, context|
  summary = payload.dig('issue', 'title')

  context[:endpoints].log_event('issue.created', summary: summary)
  context[:secrets].set('WEBHOOK_TOKEN', SecureRandom.hex(8))

  { ok: true }
end

sdk.webhook('workflow.sla_status', version: 'v1') do |payload, context|
  project_id = payload.dig('issue', 'project_id')
  events = context[:endpoints].sla_events(project_id).list(state: 'imminent', limit: 5)

  next { ok: true } if events['data'].empty?

  first = events['data'].first
  context[:endpoints].notify(
    'SLA warning',
    "Issue ##{first['issue_id']} is #{first['state']} for #{first.dig('definition', 'status')}",
    'warning'
  )

  { acknowledged: true }
end

4. Run locally¶

sdk.run!(host: '127.0.0.1', port: 8080)

Expose the Sinatra server via ngrok or deploy it directly to platforms like Heroku, Fly.io, Render, Cloud Run, or any Rack-compatible host.

5. Telemetry & feedback¶

Telemetry is enabled by default and POSTs to /api/v1/ext/telemetry using the runtime token provided in webhook payloads.

sdk = KiketSDK.new(
  telemetry_enabled: true,
  feedback_hook: proc { |record| warn "[telemetry] #{record[:event]} -> #{record[:status]}" }
)

Set KIKET_SDK_TELEMETRY_OPTOUT=1 to disable or KIKET_SDK_TELEMETRY_URL to mirror the payloads elsewhere.

6. Add a setup wizard (optional)¶

Add a guided setup experience with a setup section in your manifest:

.kiket/extension.yaml

model_version: "1.0"
extension:
  id: com.example.notifications
  name: Notification Hub
  version: 1.0.0
  delivery: http
  callback:
    url: ${EXTENSION_BASE_URL}
    secret: env.KIKET_WEBHOOK_SECRET

  configuration:
    DISCORD_WEBHOOK:
      type: string
      secret: true
      required: true
      label: Discord Webhook URL
    notify_priority:
      type: select
      options: [all, high, critical]
      default: high
      label: Notification Priority

  setup:
    - secrets:
        id: discord
        title: Connect Discord
        collect:
          - DISCORD_WEBHOOK
    - configure:
        id: settings
        title: Configure Notifications
        collect:
          - notify_priority

See the Setup Wizard Guide for all available step types.

7. Next steps¶

Explore the API reference for details on HandlerContext, secret helpers, custom data clients, and telemetry reporters.
Review the deployment cookbook for packaging, CI, and hosting patterns.