Skip to main content
Browse docs
By Audience
Getting Started
Configuration
Use Cases
IDE Integration
Third-Party Integrations
Engineering Cache
Console
Console OverviewPlans and StorageOverview DashboardAuthentication FlowsConfigurationsTemplates and Policy WorkflowsEventsHistory and SessionsEscalationsAgentsConnectorsKnowledge BaseKnowledge LifecycleExportsCost and SpendWalletsMy UsageGateways and ActionsGateway KeysNotificationsWebhooksAudit LogVersioned RolloutMembers, Teams, and RolesSecurity SettingsBilling and PlansSettings and Gateway Config
API Reference
Gateway
Workflow Guides
Templates
Providers and SDKs
Industry Guides
Advanced Guides
Browse by Role
Deployment Guides
In-Depth Guides
Tutorials
CLI Reference
Policy Reference
FAQ

Webhooks

Webhooks let you push real-time event notifications to external systems. Configure webhook endpoints to receive events when important actions occur in your Keeptrusts organization.

Use this page when​

  • You want to push real-time Keeptrusts event notifications (new events, escalations, exports, gateway health) to external systems.
  • You need to set up, test, or debug webhook delivery from the console or CLI.
  • You want to verify webhook signatures to confirm payload authenticity in your receiver.

Primary audience​

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

Managing webhooks in the console​

Settings → Webhooks provides:

  • List of configured webhook endpoints
  • Endpoint creation with event type selection
  • Delivery history and failure inspection
  • Secret rotation and testing

Creating a webhook​

  1. Go to Settings → Webhooks
  2. Click Create Webhook
  3. Enter the target URL
  4. Select which event types to subscribe to
  5. Save — the signing secret is generated automatically

Delivery history​

Each webhook shows its recent delivery history:

  • Delivery timestamp
  • HTTP response code from the target
  • Success or failure status
  • Retry attempts for failed deliveries

Testing a webhook​

Click Test to send a test payload to the endpoint. This verifies connectivity and helps you debug your receiver.

Rotating the secret​

Click Rotate Secret to generate a new signing secret. Update your receiver to verify against the new secret.

Event types​

EventDescription
event.createdNew gateway decision event
escalation.createdNew escalation raised
escalation.resolvedEscalation resolved
export.completedExport job finished
gateway.health_changedGateway health status change
budget.threshold_reachedBudget threshold exceeded
config.deployedConfiguration deployed to gateway

Verifying webhook signatures​

Each delivery includes an X-Keeptrusts-Signature header containing an HMAC signature. Verify this against your webhook secret to confirm the payload is authentic.

CLI management​

kt webhook create --url "https://example.com/hook" --events "event.created,escalation.created"
kt webhook test --id wh_abc123
kt webhook deliveries --id wh_abc123
kt webhook rotate-secret --id wh_abc123

For AI systems​

  • Canonical terms: Keeptrusts, webhooks, webhook endpoint, webhook signature, X-Keeptrusts-Signature, HMAC, event types, delivery history, signing secret.
  • Event types: event.created, escalation.created, escalation.resolved, export.completed, gateway.health_changed, budget.threshold_reached, config.deployed.
  • CLI commands: kt webhook create, kt webhook test, kt webhook deliveries, kt webhook rotate-secret.
  • Console surfaces: Settings → Webhooks (list, create, delivery history, test, rotate secret).
  • Best next pages: kt webhook, Notifications, Escalations, Gateways and Actions.

For engineers​

  • Verify the X-Keeptrusts-Signature HMAC header against your webhook secret on every delivery to confirm authenticity.
  • Use the Test button in the console to send a synthetic payload and verify connectivity before relying on production deliveries.
  • Failed deliveries are retried automatically; check delivery history for HTTP response codes to debug receiver issues.
  • Rotate the signing secret periodically with kt webhook rotate-secret --id <id> and update your receiver immediately after rotation.
  • Webhook endpoints must respond within the delivery timeout or they will be marked as failed.

For leaders​

  • Webhooks enable real-time integration with external systems (SIEM, ticketing, Slack, PagerDuty) so governance events are actionable immediately.
  • escalation.created webhooks can trigger on-call workflows, ensuring human review happens within SLA even outside business hours.
  • budget.threshold_reached webhooks provide proactive cost alerts before wallets are exhausted.
  • Signing-secret rotation is an operational hygiene requirement — include it in your credential rotation schedule.

Next steps​