Skip to main content

Webhooks

Webhooks let you receive real-time HTTP notifications when events occur in your CloudKeep vaults. Use them to trigger deployments, send alerts to Slack or Discord, or sync secrets with external systems.

What Are Webhooks?

A webhook is an HTTP POST request that CloudKeep sends to a URL you specify whenever a subscribed event occurs. Instead of polling the API to check for changes, webhooks push updates to you instantly.

Each webhook delivery includes a JSON payload describing the event, the affected resource, and a timestamp. Your endpoint should respond with a 2xx status code to acknowledge receipt.

Setting Up Webhooks

Navigate to Settings → Webhooks and click Add Webhook. You will need to provide a URL (the HTTPS endpoint, must be publicly reachable), Events (which events trigger the webhook), and a Secret key (used to sign every delivery).

After saving, CloudKeep sends a ping event to verify your endpoint is reachable. If the ping fails, the webhook is saved but marked as inactive until the endpoint responds successfully.

Supported Events

EventDescription
secret.createdA new secret was added to a vault.
secret.updatedAn existing secret’s value or metadata was changed.
secret.deletedA secret was permanently deleted.
vault.createdA new vault was created.
vault.updatedA vault’s name or settings were changed.
vault.deletedA vault and all its secrets were deleted.
member.addedA team member was granted access to a vault.
member.removedA team member’s access was revoked.
pingTest event sent when a webhook is created or tested.

Example payload for a secret.created event:

{
  "id": "evt_7xM4nQ",
  "event": "secret.created",
  "timestamp": "2025-06-11T10:30:00Z",
  "data": {
    "vaultId": "vlt_8xK2mN",
    "vaultName": "Production",
    "secretId": "sec_5bC8eF",
    "secretKey": "NEW_API_KEY",
    "type": "api_key",
    "actor": {
      "id": "usr_1xA2bC",
      "name": "Jane Developer"
    }
  }
}

Note: webhook payloads never include secret values. Only metadata (key name, type, vault) is sent to protect sensitive data.

Slack Integration

CloudKeep provides a native Slack integration that posts formatted messages to a channel of your choice.

  1. 1

    Open webhook settings

    Go to Settings → Webhooks → Add Webhook.
  2. 2

    Choose Slack

    Select Slack as the destination type.
  3. 3

    Authorise

    Click Connect to Slack to authorise CloudKeep with your Slack workspace.
  4. 4

    Pick a channel

    Choose the channel where notifications should appear.
  5. 5

    Select events

    Select the events you want to receive and save.

Slack messages include the event type, affected vault and secret key, who performed the action, and a timestamp. They are formatted with Slack Block Kit for readability.

Discord Integration

Send notifications to a Discord channel using a Discord webhook URL:

  1. 1

    Create a Discord webhook

    In Discord, go to your channel’s settings and create a new webhook under Integrations → Webhooks. Copy the webhook URL.
  2. 2

    Add webhook in CloudKeep

    Go to Settings → Webhooks → Add Webhook.
  3. 3

    Paste the URL

    Select Discord as the destination type and paste the Discord webhook URL.
  4. 4

    Save

    Choose your events and save.

CloudKeep formats Discord messages as rich embeds with colour-coded borders (green for created, yellow for updated, red for deleted).

Generic Webhooks with HMAC Verification

For custom integrations, use a generic webhook. CloudKeep signs every delivery with an HMAC-SHA256 signature so you can verify authenticity. The signature is included in the X-CloudKeep-Signature-256 header:

X-CloudKeep-Signature-256: sha256=a1b2c3d4e5f6...

Verify the signature on your server by computing the HMAC of the raw request body using your webhook secret key:

import crypto from "node:crypto"

function verifyWebhook(body: string, signature: string, secret: string): boolean {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(body, "utf-8")
    .digest("hex")

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  )
}

Always use a constant-time comparison (like timingSafeEqual) to prevent timing attacks.

Testing Webhooks

After creating a webhook, use the Test button in the webhook settings to send a ping event. You can also use a tool like webhook.site or ngrok to inspect deliveries during development, check the Delivery Log to see recent deliveries, or re-deliver any past event from the log.

Retry Behaviour

If your endpoint responds with a non-2xx status or does not respond within 10 seconds, CloudKeep retries the delivery with exponential backoff:

  • Retry 1: after 1 minute
  • Retry 2: after 5 minutes
  • Retry 3: after 30 minutes
  • Retry 4: after 2 hours
  • Retry 5: after 12 hours

After 5 failed attempts, the delivery is marked as failed. If a webhook consistently fails, CloudKeep disables it after 3 consecutive days of failures and sends you an email notification.

Next Steps