Skip to main content
Browse docs
By Audience
Getting Started
Configuration
Use Cases
IDE Integration
Third-Party Integrations
Engineering Cache
Console
API Reference
Gateway
Workflow Guides
Templates
Providers and SDKs
Industry Guides
Advanced Guides
Browse by Role
Deployment Guides
In-Depth Guides
Tutorials
CLI Reference
Overview
CLI Fundamentals
OverviewInstallationAuthenticationHealth CheckInitialize ConfigCommand Groups
Run and Manage Gateway
Investigate, Test & Export
Resources & Integrations
Knowledge BaseHistorySecretsConfig VariablesControlWebhooksAgents
IAM & Team Administration
Spend & Budgets
Advanced Features
Policy Reference
FAQ

kt webhook

The kt webhook command group manages outbound webhook endpoints for event notifications.

Use this page when​

  • You need to create, test, or rotate outbound webhook endpoints from the CLI.
  • You are inspecting delivery history or troubleshooting failed webhook deliveries.
  • You want to automate webhook provisioning for new environments.

Primary audience​

  • Primary: AI Agents, Technical Engineers
  • Secondary: Technical Leaders

CRUD Operations​

List webhooks​

kt webhook list

Get a webhook​

kt webhook get --id wh_abc123

Create a webhook​

kt webhook create --url "https://example.com/webhook" --events "event.created,escalation.created"

Update a webhook​

kt webhook update --id wh_abc123 --url "https://new-endpoint.example.com/webhook"

Delete a webhook​

kt webhook delete --id wh_abc123

Testing​

Send a test delivery to verify the webhook endpoint is reachable:

kt webhook test --id wh_abc123

Secret Rotation​

Rotate the signing secret used to verify webhook deliveries:

kt webhook rotate-secret --id wh_abc123

The new secret is printed once. Update your webhook receiver to verify against the new secret.

Delivery History​

Inspect recent webhook deliveries and their outcomes:

kt webhook deliveries --id wh_abc123

Shows delivery attempts, response codes, and failure reasons.

Webhook Payload​

Webhook deliveries include:

  • Event type and timestamp
  • Event payload (typed per event kind)
  • HMAC signature in the X-Keeptrusts-Signature header for verification

For AI systems​

  • Canonical command: kt webhook with subcommands list, get, create, update, delete, test, rotate-secret, deliveries.
  • Flags: --id, --url, --events (comma-separated event types like event.created,escalation.created).
  • Webhook verification: HMAC signature in X-Keeptrusts-Signature header.
  • Delivery inspection: kt webhook deliveries --id <id> shows attempts, status codes, and failure reasons.
  • Related pages: Webhooks concept, CLI Command Groups.

For engineers​

  • Prerequisites: Authenticated session with webhooks:write for create/update/delete/rotate; webhooks:read for list/get/deliveries.
  • Validate: After kt webhook create, run kt webhook test --id <id> to verify the endpoint is reachable and returns 200.
  • Secret rotation: kt webhook rotate-secret --id <id> prints the new secret once. Update your receiver's verification logic immediately.
  • Troubleshooting: Use kt webhook deliveries --id <id> to see failed attempts. Common issues: endpoint returning non-2xx, TLS certificate errors, or timeout (delivery times out at 30s).
  • HMAC verification: Compute HMAC-SHA256(secret, raw_body) and compare with the X-Keeptrusts-Signature header value.

For leaders​

  • Webhooks enable real-time integration with existing alerting, ticketing, and SIEM systems (Slack, PagerDuty, Splunk, etc.).
  • Event-driven notifications reduce mean time to respond for governance incidents compared to polling-based approaches.
  • Secret rotation support ensures webhook security can be maintained without endpoint downtime.
  • Delivery history provides an audit trail of notification attempts for compliance evidence.

Next steps​