Skip to main content

Secrets Management

Hooklistener provides encrypted key-value storage for sensitive data like API keys, tokens, and credentials. Secrets are encrypted at rest and can be retrieved via the API.

How it works​

Secrets are stored as name-value pairs within your organization. Values are encrypted at rest and only decrypted when explicitly requested.

Naming rules​

Secret names must follow the pattern ^[A-Z][A-Z0-9_]*$:

  • Start with an uppercase letter
  • Only uppercase letters, digits, and underscores
  • Examples: STRIPE_WEBHOOK_SECRET, API_KEY, DATABASE_URL

Creating secrets​

Dashboard​

  1. Go to Organization Settings
  2. Navigate to the secrets section
  3. Click Add Secret
  4. Enter the name and value
  5. Click Save

API​

curl -X POST https://app.hooklistener.com/api/v1/secrets \
  -H "Authorization: Bearer hklst_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "secret": {
      "name": "STRIPE_WEBHOOK_SECRET",
      "value": "whsec_abc123..."
    }
  }'

Retrieving secrets​

List secrets (metadata only)​

curl https://app.hooklistener.com/api/v1/secrets \
  -H "Authorization: Bearer hklst_your_api_key"

Values are not included in list responses.

Decrypt a secret value​

curl https://app.hooklistener.com/api/v1/secrets/<secret-id>/value \
  -H "Authorization: Bearer hklst_your_api_key"

Returns the decrypted value along with the decryption timestamp.

Updating secrets​

curl -X PUT https://app.hooklistener.com/api/v1/secrets/<secret-id> \
  -H "Authorization: Bearer hklst_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "secret": {
      "value": "whsec_new_value..."
    }
  }'

Deleting secrets​

curl -X DELETE https://app.hooklistener.com/api/v1/secrets/<secret-id> \
  -H "Authorization: Bearer hklst_your_api_key"

Use cases​

  • Store webhook signing secrets — keep Stripe, GitHub, or other signing secrets accessible to your team
  • API credentials — store third-party API keys securely
  • Configuration values — sensitive configuration that shouldn't be in source control
  • Team sharing — share credentials across team members without insecure channels

Security​

  • All secret values are encrypted at rest
  • Values are only transmitted over HTTPS
  • Access is controlled by organization membership and API key authentication
  • Secret names must be unique within an organization