Webhooks

Webhooks tell your systems that a secret changed. When someone creates, updates, or deletes a secret in a project, Krypt sends a signed HTTP POST to the URL you registered — so you can redeploy a service, invalidate a cache, or post to a team channel.

Webhook payloads contain metadata only — never secret values. A delivery tells you which key changed, in which environment, and when. It never includes the value of the secret, before or after the change. To read a value, use krypt pull or the dashboard.

Creating a webhook

Webhooks are configured per project, and only owners and admins can manage them.

Open the Webhooks tab

In your Krypt dashboard, open a project and select the Webhooks tab.

Add the endpoint

Enter a name (3–50 characters) and the URL that will receive deliveries.The URL must use https://. Private, loopback, and internal addresses are rejected — both when you save the webhook and again on every delivery.

Choose environment and events

Scope the webhook to development, staging, production, or all environments, then pick which of the three events it should receive.

Save the signing secret

On save, Krypt shows a signing secret — a 64-character hex string used to sign every delivery.It is shown once and cannot be recovered. Copy it and store it with your other secrets before closing the dialog.

If you lose the signing secret, you cannot retrieve it. Rotate it from the webhook’s menu to generate a new one — the old secret stops working immediately, so update your receiver before rotating.

Events

Three events exist:

Event	Fired when
`secret.created`	A new secret is added to an environment
`secret.updated`	An existing secret’s value is changed, or a secret is restored to an earlier version
`secret.deleted`	A secret is removed from an environment

A delivery is sent only when both conditions hold: the event is in the webhook’s subscribed list, and the webhook’s environment is all or matches the environment of the changed secret.

Restoring a secret to a previous version fires secret.updated, the same as an ordinary edit. The payload does not distinguish the two.

Payload

Every secret event sends this JSON body:

{
  "event": "secret.updated",
  "key": "DATABASE_URL",
  "environment": "production",
  "project_id": "3f9a1c62-5d84-4b7e-9c21-0e5a7d3f1b88",
  "timestamp": "2026-08-07T09:14:22.331Z"
}

Field	Type	Description
`event`	string	`secret.created`, `secret.updated`, or `secret.deleted`
`key`	string	The name of the secret that changed — not its value
`environment`	string	`development`, `staging`, or `production`
`project_id`	string	UUID of the project
`timestamp`	string	ISO 8601 timestamp of the delivery

These five fields are the entire payload. In particular, it does not identify who made the change — to see the actor, check the project’s activity log in the dashboard. Two headers accompany every delivery:

Header	Value
`X-Krypt-Signature`	`sha256=<hex digest>` — see Verifying signatures
`X-Krypt-Event`	The event name, so you can route without parsing the body

Test ping

The Test action on a webhook sends a ping so you can confirm your endpoint is reachable. The test payload has a different shape to a real event:

{
  "event": "test.ping",
  "project_id": "3f9a1c62-5d84-4b7e-9c21-0e5a7d3f1b88",
  "test": true,
  "message": "This is a test ping from Krypt",
  "timestamp": "2026-08-07T09:14:22.331Z"
}

Differences from a secret event:

There is no key and no environment field. A receiver that assumes those are always present will break on a test ping.
It carries test: true and a human-readable message.
It ignores the webhook’s event and environment filters — a test ping is delivered even if the webhook only subscribes to secret.deleted in production.

The ping is signed exactly like a real delivery, with X-Krypt-Event: test.ping. The webhook must be active — testing a disabled webhook returns an error instead of sending.

Handle test.ping explicitly in your receiver and return 200 — that way the dashboard reports a successful test, and your event-handling logic never sees a payload without a key.

Verifying signatures

Every delivery is signed with HMAC-SHA256 using your webhook’s signing secret. The digest is computed over the raw request body and sent as:

X-Krypt-Signature: sha256=<hex digest>

Verify against the raw bytes of the request body, exactly as received. If you parse the JSON and re-serialise it, key order and whitespace can differ from what Krypt signed, and the signature will not match. In Express this means using express.raw() on the webhook route — not express.json().

A complete Node.js + Express receiver:

import express from "express";
import crypto from "node:crypto";

const app = express();
const SIGNING_SECRET = process.env.KRYPT_SIGNING_SECRET;

app.post(
  "/krypt-webhook",
  // express.raw() keeps req.body as a Buffer — the exact bytes Krypt signed.
  express.raw({ type: "application/json" }),
  (req, res) => {
    const received = req.get("X-Krypt-Signature") ?? "";
    const expected =
      "sha256=" +
      crypto
        .createHmac("sha256", SIGNING_SECRET)
        .update(req.body)
        .digest("hex");

    // Constant-time compare. timingSafeEqual throws on length mismatch,
    // so check length first.
    const a = Buffer.from(received);
    const b = Buffer.from(expected);
    if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
      return res.status(401).send("Invalid signature");
    }

    const payload = JSON.parse(req.body.toString("utf8"));

    if (payload.event === "test.ping") {
      return res.status(200).send("ok");
    }

    console.log(`${payload.event}: ${payload.key} in ${payload.environment}`);

    // Respond 2xx quickly — Krypt times out after 10 seconds.
    res.status(200).send("ok");
  }
);

app.listen(3000);

Reject any request whose signature does not match. An unverified request proves nothing about its origin.

Endpoint authentication

If your receiver needs its own credentials on top of the signature, set an auth type when creating the webhook. Krypt then adds an Authorization header to every delivery:

Auth type	Header sent
`none`	No `Authorization` header (default)
`bearer`	`Authorization: Bearer <your token>`
`basic`	`Authorization: Basic <base64 of username:password>`

Basic credentials are entered as username:password. Stored credentials are encrypted at rest and never returned in full by the API — reads show a masked value only. This is optional and independent of signing. The signature is always sent; endpoint auth is for receivers that additionally gate on a token.

Limitations

Current behaviour, stated plainly so you can design your receiver around it:

One delivery attempt, no retries. Krypt sends each event once, with a 10-second timeout. If your endpoint is down, returns a non-2xx status, or times out, the event is not retried and is lost. The failure is recorded in the project’s activity log and as the webhook’s last status, but it is never resent.
No delivery ID. Payloads carry no unique event identifier, so there is nothing to deduplicate on if you receive the same event twice.
No replay protection. There is no timestamp header and no expiry on a signature. A captured delivery remains valid indefinitely if replayed against your endpoint. The timestamp inside the body is signed — you can reject old payloads yourself by comparing it against the current time.
No actor. The payload does not say who made the change.

Because nothing is retried, your only record of a delivery is the dashboard: each webhook in the project’s Webhooks tab shows when it last fired and the HTTP status it returned, and the project’s activity log lists every individual success and failure. Additional constraints worth knowing:

Only https:// URLs are accepted; private, loopback, and internal addresses are blocked, and the URL is re-validated on every delivery.
Only owners and admins can create, edit, test, or delete webhooks.
On a Free project that is over the team-member cap, the project becomes read-only and webhooks stop firing entirely — including test pings.

Next steps

Roles and permissions — who can manage webhooks
Encryption and security — how Krypt protects stored secrets
CLI commands — push and pull the secrets these events describe

Getting started

CLI

Concepts

Help

Creating a webhook

Events

Payload

Test ping

Verifying signatures

Endpoint authentication

Limitations

Next steps

​Creating a webhook

​Events

​Payload

​Test ping

​Verifying signatures

​Endpoint authentication

​Limitations

​Next steps

Creating a webhook

Events

Payload

Test ping

Verifying signatures

Endpoint authentication

Limitations

Next steps