Python SDK Quickstart

Build, run, and observe your first Kiket extension in minutes using the official Python SDK.

1. Install dependencies

uv add kiket-sdk
uv add --dev ruff pytest pytest-asyncio

The SDK targets Python 3.11+ and ships typed stubs, so type checkers such as MyPy work out of the box.

2. Configure secrets

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

Variable	Purpose
KIKET_WEBHOOK_SECRET	Shared secret used to verify inbound webhook signatures.
KIKET_WORKSPACE_TOKEN	Workspace token for outbound API calls (logs, metrics, secret store).
KIKET_BASE_URL (optional)	Override the default https://kiket.dev base URL for staging/self-hosted setups.

You can load values from .env files using python-dotenv, or inject them via your hosting platform’s secret manager.

3. Create your extension

main.py

from kiket_sdk import KiketSDK

sdk = KiketSDK(
    extension_id="com.example.campaigns",
    extension_version="1.0.0",
)

@sdk.webhook("campaign.created", version="v1")
async def handle_campaign(payload, context):
    campaign = payload["campaign"]
    await context.endpoints.log_event(
        f"Campaign {campaign['name']} created",
        campaign_id=campaign["id"],
    )
    await context.endpoints.emit_metric(
        "campaign.created",
        1,
    )
    return {"ok": True}

if __name__ == "__main__":
    sdk.run(host="0.0.0.0", port=8080)

The SDK auto-loads .kiket/extension.yaml if present, so you can centralize IDs, versions, and default settings alongside your manifest.

4. Run locally

uv run python main.py

Send a signed webhook to test the handler:

python scripts/send_webhook.py \
  --event campaign.created \
  --secret "$KIKET_WEBHOOK_SECRET" \
  --payload '{"campaign":{"id":123,"name":"Launch"}}'

The SDK exposes both /webhooks/<event> and /v/<version>/webhooks/<event> routes. Provide the event version via X-Kiket-Event-Version, a version query param, or the /v/<version> path.

5. Monitor with the built-in health endpoint

curl http://localhost:8080/health

Response:

{
  "status": "ok",
  "extension_id": "com.example.campaigns",
  "extension_version": "1.0.0",
  "registered_events": ["campaign.created@v1"]
}

6. Enable telemetry (optional)

Telemetry is opt-in and records handler duration/success metadata. Provide a callback or hosted endpoint:

from kiket_sdk import TelemetryRecord

async def telemetry_hook(record: TelemetryRecord):
    print(f"{record.event}@{record.version} {record.status} {record.duration_ms:.1f}ms")

sdk = KiketSDK(
    webhook_secret="secret",
    workspace_token="wk_test",
    telemetry_enabled=True,
    feedback_hook=telemetry_hook,
)

Set KIKET_SDK_TELEMETRY_URL to stream JSON payloads to your observability stack, or KIKET_SDK_TELEMETRY_OPTOUT=1 to disable telemetry globally.

7. Add a setup wizard (optional)

Help users configure your extension with a guided setup wizard. Add a setup section to your manifest:

.kiket/extension.yaml

model_version: "1.0"
extension:
  id: com.example.campaigns
  name: Campaign Manager
  version: 1.0.0
  delivery: http
  callback:
    url: ${EXTENSION_BASE_URL}
    secret: env.KIKET_WEBHOOK_SECRET

  configuration:
    API_KEY:
      type: string
      secret: true
      required: true
      label: API Key
      description: Your campaign platform API key
    auto_sync:
      type: boolean
      default: "true"
      label: Auto-sync campaigns

  setup:
    - secrets:
        id: credentials
        title: Connect Your Account
        description: Enter your API credentials
        collect:
          - API_KEY
    - configure:
        id: settings
        title: Configure Settings
        collect:
          - auto_sync
    - test:
        id: verify
        title: Verify Connection
        endpoint: /test-connection

The wizard walks users through each step after installation. See the Setup Wizard Guide for all step types and options.

8. Deploy

• Containerize with the provided FastAPI app (sdk.run).
• Point your hosting platform (Cloud Run, ECS, Kubernetes) at the ASGI server.
• Configure secrets through the Kiket secret manager (kiket secrets set ...) or environment variables.
• Add the webhook URL to your extension manifest (delivery.callback.url).

Next steps - Explore the deployment cookbook for multi-version routing, secret automation, and replay pipelines. - Dive into the API reference for details on HandlerContext, endpoint helpers, and telemetry payloads. - Follow the tutorial to build a production-ready marketing automation extension end to end.