Secrets

Secrets provide secure, encrypted storage for sensitive data like API keys, tokens, and passwords that your webhooks and transformations need to access. Hooklistener's secrets management system ensures your sensitive data is protected with enterprise-grade encryption while remaining easily accessible to your automation workflows.

Overview

Secrets are encrypted key-value pairs stored securely within your organization. They solve the critical security challenge of managing sensitive data in webhook automation:

Secure storage: All secrets are encrypted using AES encryption with key rotation support
Organization isolation: Complete isolation between organizations - your secrets are never accessible to other users
Runtime access: Secrets are available to transformations via the standard process.env interface
Audit tracking: Usage tracking with last_used_at timestamps for compliance
Soft deletion: Deleted secrets are preserved for audit purposes

Key Features

Enterprise-Grade Security

Hooklistener's secrets system implements multiple layers of security:

Encryption at Rest

AES encryption with unique keys per secret
Encrypted values and encrypted keys stored separately
Support for key versioning and rotation
Master key management through secure vault system

Access Controls

Organization-scoped access - secrets never cross organizational boundaries
API token authentication required for all operations
Execution-only decryption - secrets only available during transformation runs
No logging of secret values - audit trail without exposing sensitive data

Key Rotation

Automated key rotation capabilities
Background workers for scheduled rotation
Zero-downtime rotation - secrets remain accessible during rotation
Rotation monitoring and failure handling

Seamless Integration

Secrets integrate naturally into your webhook workflows in two powerful ways:

1. URL Template Substitution Use secrets directly in destination URLs with template syntax:

https://api.telegram.org/bot{{TELEGRAM_BOT_TOKEN}}/sendMessage
https://hooks.slack.com/services/{{SLACK_WEBHOOK_PATH}}
https://api.example.com/webhook?token={{API_TOKEN}}&secret={{WEBHOOK_SECRET}}

This allows you to:

Keep sensitive tokens out of your connection configuration
Securely embed API keys, bot tokens, and webhook secrets in URLs
Maintain clean, readable connection setups without exposing credentials
Automatically rotate credentials by updating the secret value

2. Transformation Access Access secrets programmatically within transformations:

addHandler('transform', async (request, context) => {
  // Access any organization secret via process.env
  const apiKey = process.env.API_KEY;
  const botToken = process.env.TELEGRAM_BOT_TOKEN;
  const webhookSecret = process.env.WEBHOOK_SECRET;
  
  // Use in your transformation logic
  return {
    ...request,
    headers: {
      ...request.headers,
      'Authorization': `Bearer ${apiKey}`,
      'X-Bot-Token': botToken
    }
  };
});

Usage Tracking

Automatic last_used_at timestamps when secrets are accessed
Applies to both URL substitution and transformation access
Helps identify unused secrets for cleanup
Compliance and audit trail support

Security Model

Data Protection

At Rest

Individual secret values encrypted with unique keys
Keys encrypted with master vault key
Database stores only encrypted data - never plaintext
Backup and disaster recovery maintain encryption

In Transit

HTTPS/TLS for all API communications
Secrets transmitted only during API operations
No network transmission during transformation execution
Secure key exchange protocols

In Memory

Secrets loaded into transformation sandbox only during execution
Memory cleared immediately after transformation completes
No persistence in transformation runtime environment
Isolated execution prevents cross-contamination

Access Patterns

Who Can Access Secrets

Organization members with valid API tokens
Transformations running within your organization
Background rotation workers (internal system only)

When Secrets Are Accessed

During transformation execution via process.env
Through API calls for management operations
During automated key rotation processes

Where Secrets Are Never Stored

Application logs or debug output
Transformation execution logs
Error messages or stack traces
Client-side code or browser storage

Naming Conventions

Secrets follow standard environment variable naming patterns:

Required Format

Must start with uppercase letter: A-Z
Can contain uppercase letters, numbers, and underscores: A-Z0-9_
Examples: API_KEY, TELEGRAM_BOT_TOKEN, WEBHOOK_SECRET_2024

Best Practices

✅ Good Names:
API_KEY
SLACK_BOT_TOKEN
DATABASE_URL
WEBHOOK_SECRET
PAYMENT_API_KEY

❌ Bad Names:
api_key          (must start with uppercase)
Api-Key          (no hyphens allowed)  
123_TOKEN        (must start with letter)
My Secret        (no spaces allowed)

Limits and Constraints

Storage Limits

Secret name: 1-255 characters
Secret value: 1-10,000 characters (10KB)
Description: Up to 1,000 characters
Secrets per organization: No explicit limit (reasonable usage expected)

Plan Requirements

Free Plan: Secrets are not available
Team Plan: Full secrets management with standard features
Enterprise Plan: Enhanced security, monitoring, and rotation features

Performance Considerations

Access Performance

Secrets are loaded once per transformation execution
Multiple process.env accesses within single transformation are cached
No network round-trips required during transformation execution
Minimal latency impact on webhook delivery

Rotation Impact

Key rotation happens in background with zero downtime
Existing executions continue with current keys
New executions automatically use rotated keys
No service interruption during rotation process

Soft Deletion and Audit

Deletion Behavior

When you delete a secret:

Secret marked as is_active: false but not physically removed
Immediately unavailable to new transformation executions
Historical audit trail preserved
Can be recovered by support if needed (Enterprise plans)

Audit Capabilities

Creation tracking: When and by whom secrets were created
Usage tracking: Last accessed timestamp for each secret
Rotation history: When keys were last rotated
Modification audit: Changes to secret names and descriptions

Integration with Transformations

Automatic Loading

Secrets are automatically made available to transformations:

addHandler('transform', async (request, context) => {
  // All organization secrets available via process.env
  console.log(`Loaded ${Object.keys(process.env).length} secrets`);
  
  // Check if specific secrets exist
  if (!process.env.API_KEY) {
    console.log('Warning: API_KEY not configured');
    return request; // Skip transformation
  }
  
  // Use secrets safely
  const headers = {
    ...request.headers,
    'Authorization': `Bearer ${process.env.API_KEY}`
  };
  
  return { ...request, headers };
});

Error Handling

addHandler('transform', async (request, context) => {
  try {
    // Use secrets with error handling
    const apiKey = process.env.API_KEY;
    if (!apiKey) {
      throw new Error('API_KEY secret not configured');
    }
    
    return transformWithApiKey(request, apiKey);
  } catch (error) {
    console.log('Transformation error:', error.message);
    // Return original request on secret-related errors
    return request;
  }
});

Security Best Practices

Secret Management

Use descriptive names: STRIPE_API_KEY not just API_KEY
Rotate regularly: Set up automated rotation schedules
Monitor usage: Review last_used_at to identify unused secrets
Clean up unused secrets: Remove secrets that are no longer needed
Use minimum permissions: API keys should have minimal required permissions

Development Practices

Never log secret values: Use console.log('Using API key:', !!process.env.API_KEY)
Validate secret presence: Check if secrets exist before using them
Handle missing secrets gracefully: Don't fail entire transformations
Use different secrets per environment: Separate dev/staging/production secrets

Billing and Features

Team Plan

Complete secrets management API
AES encryption with secure key management
Organization isolation and access controls
Usage tracking and audit trails
Standard rotation capabilities

Enterprise Plan

Everything in Team Plan
Advanced monitoring and alerting
Configurable rotation schedules
Enhanced audit logging
Priority support for security issues
Custom integration assistance
Compliance reporting features

Next Steps

Ready to secure your webhook automation with secrets?

Learn to manage secrets with our step-by-step guide
Explore examples for common use cases and patterns
Review security best practices for production deployments
Check the API reference for complete endpoint documentation

Secrets provide the foundation for secure webhook automation, enabling you to connect to any service while keeping your sensitive data protected and properly managed.

Overview​

Key Features​

Enterprise-Grade Security​

Seamless Integration​

Security Model​

Data Protection​

Access Patterns​

Naming Conventions​

Required Format​

Best Practices​

Limits and Constraints​

Storage Limits​

Plan Requirements​

Performance Considerations​

Access Performance​

Rotation Impact​

Soft Deletion and Audit​

Deletion Behavior​

Audit Capabilities​

Integration with Transformations​

Automatic Loading​

Error Handling​

Security Best Practices​

Secret Management​

Development Practices​

Billing and Features​

Team Plan​

Enterprise Plan​

Next Steps​