Extension Delivery Contract

Every Kiket extension receives events over HTTPS using the same JSON schema and headers. This page documents the payload, headers, and expected responses so you can confidently validate signatures, consume runtime secrets, and return actionable status codes.

Delivery Flow

1. Kiket renders the event payload and injects runtime metadata (authentication token, API context, secrets).
2. The runtime issues an HTTPS POST to your manifest’s delivery.callback.url.
3. Your service responds with a JSON body (or empty 200) indicating whether the action succeeded.
4. Kiket records the response, enqueues telemetry, and retries on transient failures.

Request Headers

Header	Description
X-Kiket-Event	Event name (e.g., issue.created, workflow.sla_status).
X-Kiket-Event-Version	Version requested in the path/header/query string.
X-Kiket-Invocation	Unique identifier for the invocation. Useful for correlating logs.
X-Kiket-Project / X-Kiket-Organization	Numeric identifiers for the project/organization that triggered the event.
X-Kiket-Signature	HMAC-SHA256 signature of the raw body using the manifest’s delivery secret (or override secret).

Request Body

{
  "event": "workflow.sla_status",
  "event_version": "v1",
  "issue": {
    "id": 4231,
    "project_id": 27,
    "title": "Restore checkout webhooks"
  },
  "definition": {
    "id": 9,
    "status": "in_progress",
    "issue_type": "incident"
  },
  "metrics": {
    "duration_minutes": 68,
    "overdue_minutes": 8
  },
  "authentication": {
    "token_type": "runtime",
    "runtime_token": "rt_123...",
    "expires_at": "2025-11-08T11:31:42Z",
    "scopes": ["project:27"]
  },
  "secrets": {
    "MAKE_COM_TOKEN": "********",
    "ONCALL_WEBHOOK": "********"
  },
  "secret_status": {
    "missing": ["SENTRY_DSN"]
  },
  "api": {
    "base_url": "https://kiket.dev",
    "runtime_header": "X-Kiket-Runtime-Token"
  },
  "context": {
    "user_id": 91,
    "workspace": "acme"
  }
}

Field Reference

• event / event_version – values requested in the URL or X-Kiket-Event-Version header.
• issue, definition, metrics, context – event-specific payload, unchanged from the workflow runtime.
• authentication – short-lived runtime token plus metadata. Use runtime_token for outbound calls to /api/v1/ext/** when present; fall back to your extension API key otherwise.
• secrets – key/value pairs fetched from Extensions::SecretStore just-in-time. Values are never persisted on disk.
• secret_status.missing – list of requested keys that were unavailable so you can prompt operators.
• api – base URL and header name to re-use when calling back into Kiket.

Responses

• Success – return 2xx and optional JSON body (e.g., { "status": "allow" } or { "ok": true }). The delivery job records the response body for audit logs.
• Retryable failure – return 5xx, 429, or throw a network error. Required hooks retry exponentially (up to 5 times) and surface alerts when all attempts fail.
• Non-retryable failure – return 4xx (other than 429). Required hooks halt the originating workflow unless you explicitly mark the hook as required: false in the manifest.

Include meaningful body payloads for troubleshooting; they appear in Project → Extensions → Activity and the diagnostics column of extension_events.

SDK Guidance

• TypeScript/JavaScript: context.endpoints.rateLimit() exposes /api/v1/ext/rate_limit, while context.endpoints.customData and context.endpoints.slaEvents handle scoped helpers automatically.
• Python/Ruby SDKs are aligning on the same handler context (authentication, secrets, API metadata). Partner updates land in the internal SDK parity tracker that your account team can share.

For code samples that parse the payload, verify signatures, and use runtime tokens, consult the SDK quickstarts or the TypeScript README inside the repository. Cross-language parity progress is published through the partner portal instead of the public repository.