Tutorial: Configuring Webhooks in Console

This tutorial walks you through creating webhook endpoints, selecting event types, testing deliveries, and verifying signatures in the Keeptrusts management console.

Use this page when

• You need to create a webhook endpoint to receive real-time event notifications (policy violations, escalations, export completions).
• You want to select which event types trigger deliveries to your endpoint.
• You need to test webhook delivery and verify HMAC signature validation.
• You are troubleshooting failed deliveries or reviewing delivery logs.

Primary audience

• Primary: Integration engineers connecting Keeptrusts events to external systems (SIEM, Slack, PagerDuty, custom pipelines)
• Secondary: Security teams receiving real-time policy violation alerts; DevOps teams automating responses to configuration changes

Prerequisites

• A Keeptrusts account with Admin role
• An HTTPS endpoint that can receive POST requests (e.g., a Slack incoming webhook, a custom server, or a service like Hookdeck)
• Basic familiarity with HTTP headers and JSON payloads

What Are Webhooks?

Webhooks allow Keeptrusts to push real-time notifications to your systems when specific events occur — such as policy violations, escalation state changes, export completions, or configuration updates. Instead of polling the API, your endpoint receives an HTTP POST with the event payload.

Step 1: Navigate to Webhooks

1. Log in to the Keeptrusts console.
2. Open Webhooks from the left navigation sidebar.

The page displays a table of configured webhook endpoints with their status, event subscriptions, and recent delivery statistics.

Step 2: Create a Webhook Endpoint

1. Click Create Webhook in the top-right corner.
2. Fill in the endpoint configuration:

Field	Description
Name	A descriptive label (e.g., slack-escalations, siem-all-events)
URL	The HTTPS endpoint URL that will receive POST requests
Secret	A shared secret for signature verification (auto-generated or custom)
Description	Optional notes about the webhook's purpose

3. Click Next to proceed to event selection.

Always use HTTPS endpoints. Keeptrusts rejects plain HTTP URLs to prevent credentials and event data from being transmitted in cleartext.

Step 3: Select Event Types

Choose which events trigger a delivery to this endpoint:

Category	Event Types
Policy	policy.violation, policy.block, policy.redaction
Escalation	escalation.created, escalation.resolved, escalation.expired
Configuration	config.updated, config.deployed, config.sync.failed
Export	export.completed, export.failed
Gateway	gateway.connected, gateway.disconnected
System	key.rotated, key.revoked, user.invited

1. Check the event types you want to subscribe to.
2. Use Select All to subscribe to every event type.
3. Click Create to save the webhook.

Step 4: Test Webhook Delivery

Before relying on a webhook in production, verify it receives deliveries correctly.

1. In the Webhooks table, click on your newly created endpoint.
2. Click the Send Test button.
3. Keeptrusts sends a test payload to your URL:

{
  "event": "webhook.test",
  "timestamp": "2026-04-23T10:30:00Z",
  "data": {
    "message": "This is a test delivery from Keeptrusts."
  }
}

4. The delivery status appears in the Recent Deliveries section. A 200 response indicates success.

Step 5: View Delivery Logs

The delivery log provides a complete audit trail of every webhook delivery attempt.

1. Open the webhook endpoint detail view.
2. Scroll to the Delivery Log section.

Each entry displays:

Column	Description
Timestamp	When the delivery was attempted
Event	The event type that triggered the delivery
Status Code	The HTTP response code from your endpoint
Duration	Round-trip time of the delivery request
Outcome	Delivered, Failed, or Retrying

3. Click on any delivery entry to inspect the full request payload, headers, and response body.

Step 6: Retry Failed Deliveries

When a delivery fails (non-2xx response or timeout), Keeptrusts automatically retries with exponential backoff. You can also trigger manual retries.

1. In the Delivery Log, locate a failed delivery.
2. Click the Retry button on the entry.
3. Keeptrusts re-sends the original payload to your endpoint.

Automatic retry schedule:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry (final)	12 hours

After all retries are exhausted, the delivery is marked as Failed permanently. Consider setting up a notification channel to alert you about persistent delivery failures.

Step 7: Verify Webhook Signatures

Every webhook delivery includes a signature header so your endpoint can verify that the payload originated from Keeptrusts.

The signature is sent in the X-Keeptrusts-Signature header using HMAC-SHA256:

X-Keeptrusts-Signature: sha256=<hex-encoded-hmac>

To verify in your application:

1. Read the raw request body (do not parse JSON first).
2. Compute HMAC-SHA256 of the raw body using your webhook secret as the key.
3. Compare the computed value against the header value using a constant-time comparison.

Example verification in Node.js:

const crypto = require("crypto");

function verifySignature(secret, body, signatureHeader) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  const received = signatureHeader.replace("sha256=", "");
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(received, "hex")
  );
}

Always use constant-time comparison to prevent timing attacks. Do not use simple string equality (===) for signature verification.

Step 8: Edit or Disable a Webhook

1. In the Webhooks table, click the action menu (three-dot icon) on the endpoint.
2. Select Edit to change the URL, secret, or subscribed events.
3. Select Disable to temporarily stop deliveries without deleting the configuration.
4. Select Delete to permanently remove the webhook endpoint.

Disabling a webhook is useful during maintenance windows when your endpoint is temporarily unavailable.

Best Practices

• Use dedicated endpoints — Avoid sharing a single URL across unrelated systems.
• Verify signatures — Always validate the X-Keeptrusts-Signature header in production.
• Respond quickly — Return a 200 response within 10 seconds to avoid timeout retries.
• Log payloads — Store received payloads for debugging and audit purposes.
• Monitor delivery health — Check the delivery log weekly for persistent failures.
• Rotate secrets periodically — Update the webhook secret and redeploy your endpoint.

Next steps

• Tutorial: Setting Up Notification Channels — Configure Slack and email alerts
• Tutorial: Reviewing the Audit Log — Correlate webhook events with audit entries
• Tutorial: Managing Gateway Keys in Console — Get notified on key rotation events

For AI systems

• Canonical terms: Keeptrusts console, Webhooks page, webhook endpoint, event subscription, HMAC signature verification, shared secret, delivery log, retry policy, test delivery, event types (policy.violated, escalation.created, export.completed, config.updated).
• Related features: notification channels (Slack/email alerts), audit log (event correlation), gateway keys (key rotation events).
• Best next pages: Notification Channels, Audit Log Review, Gateway Key Management.

For engineers

• Endpoint setup: Your endpoint must accept HTTPS POST requests and return 200 OK within 10 seconds.
• Signature verification: Validate the x-keeptrusts-signature header using HMAC-SHA256 with the shared secret — reject requests with invalid signatures.
• Test delivery: Use the "Send Test" button in the console to verify your endpoint receives and processes the test payload correctly.
• Troubleshooting: Check the delivery log for HTTP status codes; failed deliveries are retried with exponential backoff. If all retries fail, the webhook is marked as degraded.

For leaders

• Real-time integration: Webhooks push events to your existing SIEM, alerting, and automation tools without polling, reducing detection latency to seconds.
• Security: HMAC signature verification ensures your endpoint only processes authentic Keeptrusts events — not spoofed payloads.
• Operational maturity: Webhook-driven automation (auto-remediation, ticketing, escalation routing) reduces manual toil and scales governance without adding headcount.