Enterprise Security

Hookbase provides enterprise-grade security features to protect your webhook infrastructure, ensure reliable delivery, and meet compliance requirements.

Security Features

Feature	Description	Guide
Signature Verification	Validate webhook authenticity	Sources
IP Filtering	Allowlist/denylist source IPs	IP Filtering
Field Encryption	Encrypt sensitive payload fields	Field Encryption
Circuit Breaker	Pause failing routes automatically	Circuit Breaker
Notification Channels	Real-time failure alerts	Notification Channels
Audit Logs	Track all configuration changes	Audit Logs
Deduplication	Prevent duplicate event processing	Deduplication

API Key Management

Key Rotation

Rotate API keys regularly to limit the blast radius of a compromised key. Hookbase supports zero-downtime rotation:

Create a new key before revoking the old one
Update all consumers (CI/CD, scripts, integrations) to use the new key
Monitor usage — check lastUsedAt on the old key to confirm nothing still depends on it
Revoke the old key once all consumers are migrated

curlJavaScriptPython

bash

# 1. Create new key
curl -X POST https://api.hookbase.app/api/api-keys \
  -H "Authorization: Bearer whr_your_current_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API (rotated 2024-02)",
    "scopes": ["read", "write"],
    "expiresInDays": 90
  }'

# 2. After migrating consumers, revoke old key
curl -X DELETE https://api.hookbase.app/api/api-keys/key_old123 \
  -H "Authorization: Bearer whr_your_new_key"

javascript

// 1. Create new key
const newKey = await fetch('https://api.hookbase.app/api/api-keys', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer whr_your_current_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Production API (rotated 2024-02)',
    scopes: ['read', 'write'],
    expiresInDays: 90
  })
}).then(r => r.json());

// Store newKey.key securely — only shown once

// 2. After migrating consumers, revoke old key
await fetch('https://api.hookbase.app/api/api-keys/key_old123', {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${newKey.key}` }
});

python

import requests

# 1. Create new key
new_key = requests.post(
    'https://api.hookbase.app/api/api-keys',
    headers={
        'Authorization': 'Bearer whr_your_current_key',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'Production API (rotated 2024-02)',
        'scopes': ['read', 'write'],
        'expiresInDays': 90
    }
).json()

# Store new_key['key'] securely — only shown once

# 2. After migrating consumers, revoke old key
requests.delete(
    'https://api.hookbase.app/api/api-keys/key_old123',
    headers={'Authorization': f'Bearer {new_key["key"]}'}
)

TIP

Set expiresInDays on all keys. Keys that expire force regular rotation and reduce the risk of forgotten, long-lived credentials.

Key Storage Best Practices

Environment	Storage Method
CI/CD (GitHub Actions)	Repository secrets (`${{ secrets.HOOKBASE_API_KEY }}`)
CI/CD (GitLab)	CI/CD variables (masked, protected)
Server applications	Environment variables or secrets manager (AWS Secrets Manager, Vault)
Local development	`.env` file (never committed — add to `.gitignore`)
Kubernetes	K8s Secrets or external secrets operator

Never:

Commit API keys to version control
Log API keys in application output
Share keys across environments (use separate keys for dev/staging/production)
Use admin scope when narrower scopes suffice

Source Secret Rotation

Rotate the signing secret for a source when you suspect it has been compromised:

bash

curl -X POST https://api.hookbase.app/api/sources/src_abc123/rotate-secret \
  -H "Authorization: Bearer whr_your_api_key"

WARNING

Rotating a source secret immediately invalidates the old secret. Update the secret in your webhook provider (GitHub, Stripe, etc.) before incoming webhooks will fail signature verification.

Replay Attack Prevention

Webhook replay attacks occur when an attacker intercepts a valid webhook and re-sends it. Hookbase provides multiple layers of defense:

1. Signature Verification

Always enable signature verification on sources. Each provider uses a unique signing mechanism:

Provider	Signature Header	Algorithm
GitHub	`X-Hub-Signature-256`	HMAC-SHA256
Stripe	`Stripe-Signature`	HMAC-SHA256 with timestamp
Shopify	`X-Shopify-Hmac-Sha256`	HMAC-SHA256 (base64)
Custom	Configurable	HMAC-SHA256

bash

curl -X POST https://api.hookbase.app/api/sources \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stripe Payments",
    "slug": "stripe",
    "verificationConfig": {
      "type": "stripe",
      "secret": "whsec_..."
    },
    "rejectInvalidSignatures": true
  }'

Setting rejectInvalidSignatures: true returns 401 Unauthorized for any webhook that fails signature validation.

2. Deduplication

Enable deduplication to reject webhooks that have already been processed:

bash

curl -X PATCH https://api.hookbase.app/api/sources/src_abc123 \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "dedupEnabled": true,
    "dedupStrategy": "provider_id",
    "dedupWindowHours": 24
  }'

Dedup strategies:

provider_id — Uses the provider's event ID (e.g., GitHub's X-GitHub-Delivery, Stripe's event id)
payload_hash — SHA-256 hash of the entire payload body
custom_header — Uses a specific header value as the dedup key

See Deduplication Guide for details.

3. Timestamp Validation

Stripe and some providers include a timestamp in the signature. Hookbase validates that the timestamp is within an acceptable window (default: 5 minutes), rejecting stale webhooks that could be replays.

4. IP Filtering

Restrict webhook ingestion to known provider IP ranges:

bash

curl -X PATCH https://api.hookbase.app/api/sources/src_abc123 \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "ipFilterMode": "allowlist",
    "ipAllowlist": [
      "140.82.112.0/20",
      "192.30.252.0/22",
      "185.199.108.0/22"
    ]
  }'

GitHub, Stripe, and other providers publish their webhook IP ranges. See IP Filtering for provider-specific IP lists.

Multi-Tenant Security

When using Hookbase across multiple teams or customers:

Organization Isolation

Every resource in Hookbase is scoped to an organization. There is no cross-organization data access:

Sources, destinations, routes, events, and deliveries are isolated per organization
API keys are scoped to a single organization
Audit logs track actions within each organization independently

Role-Based Access Control

Assign the minimum necessary role to each team member:

Role	Can View	Can Edit	Can Manage Members	Can Delete Org
Viewer	Yes	No	No	No
Member	Yes	Yes	No	No
Admin	Yes	Yes	Yes	No
Owner	Yes	Yes	Yes	Yes

Scoped API Keys

Create separate API keys for each integration with the minimum required scopes:

bash

# Read-only key for monitoring dashboards
curl -X POST https://api.hookbase.app/api/api-keys \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Monitoring Dashboard", "scopes": ["read"]}'

# Write key for CI/CD pipeline (sources and routes only)
curl -X POST https://api.hookbase.app/api/api-keys \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI/CD Pipeline", "scopes": ["read", "write"]}'

Field Encryption for PII

When handling multi-tenant webhook data that contains PII, encrypt sensitive fields before storage:

bash

curl -X POST https://api.hookbase.app/api/sources \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Webhooks",
    "slug": "customer-events",
    "encryptFields": [
      "$.customer.email",
      "$.customer.phone",
      "$.payment.card_number",
      "$.customer.address"
    ],
    "maskFields": [
      "$.customer.email",
      "$.payment.card_number"
    ]
  }'

Encrypted fields are stored using AES-256-GCM and are masked in the dashboard UI. See Field Encryption for details.

Securing Destination Endpoints

Authenticate Outbound Webhooks

Configure destinations with authentication so your receiving services can verify requests came from Hookbase:

bash

curl -X POST https://api.hookbase.app/api/destinations \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Internal API",
    "url": "https://api.yourapp.com/webhooks",
    "authType": "bearer",
    "authConfig": {
      "token": "your-internal-auth-token"
    },
    "headers": {
      "X-Hookbase-Source": "production"
    }
  }'

Supported auth types:

Type	Description
`none`	No authentication
`bearer`	Bearer token in Authorization header
`basic`	HTTP Basic Authentication
`api_key`	API key in a custom header
`custom_header`	Any custom header/value pair

HTTPS Only

All destination URLs must use HTTPS. Hookbase rejects http:// destination URLs to prevent webhook payloads from being transmitted in plaintext.

Timeout Configuration

Set appropriate timeouts to prevent resource exhaustion:

json

{
  "timeoutMs": 30000,
  "retryPolicy": {
    "maxRetries": 5,
    "initialDelay": 1000,
    "maxDelay": 60000,
    "backoffMultiplier": 2
  }
}

Production Security Checklist

Use this checklist before going to production:

Webhook Ingestion

[ ] Signature verification enabled on all sources (rejectInvalidSignatures: true)
[ ] IP filtering configured for known provider IP ranges
[ ] Rate limiting set to prevent abuse (rateLimitPerMinute)
[ ] Deduplication enabled to prevent replay attacks
[ ] Field encryption configured for PII fields

API Access

[ ] API keys have expiration dates set
[ ] Keys use minimum required scopes (not admin unless necessary)
[ ] Separate keys for each environment (dev, staging, production)
[ ] Keys stored in secrets manager, not in code
[ ] Unused keys revoked

Delivery

[ ] All destination URLs use HTTPS
[ ] Destinations configured with authentication
[ ] Circuit breakers enabled on critical routes
[ ] Failover destinations configured for high-priority routes
[ ] Retry policies tuned for each destination

Monitoring

[ ] Notification channels configured for delivery failures
[ ] Notification channels configured for circuit breaker trips
[ ] Audit logs reviewed periodically
[ ] API key usage monitored (lastUsedAt)

Team Access

[ ] All members assigned appropriate roles (not everyone needs Admin)
[ ] Viewers used for dashboards and monitoring tools
[ ] Owner role limited to one trusted person

IP Filtering — Restrict webhook origins by IP
Field Encryption — Encrypt sensitive payload fields
Circuit Breaker — Automatically pause failing routes
Failover Destinations — Route to backup destinations
Notification Channels — Alert on failures
Audit Logs — Track configuration changes
Deduplication — Prevent duplicate processing

Enterprise Security ​

Security Features ​

API Key Management ​

Key Rotation ​

Key Storage Best Practices ​

Source Secret Rotation ​

Replay Attack Prevention ​

1. Signature Verification ​

2. Deduplication ​

3. Timestamp Validation ​

4. IP Filtering ​

Multi-Tenant Security ​

Organization Isolation ​

Role-Based Access Control ​

Scoped API Keys ​

Field Encryption for PII ​

Securing Destination Endpoints ​

Authenticate Outbound Webhooks ​

HTTPS Only ​

Timeout Configuration ​

Production Security Checklist ​

Webhook Ingestion ​

API Access ​

Delivery ​

Monitoring ​

Team Access ​

Related Guides ​

Enterprise Security

Security Features

API Key Management

Key Rotation

Key Storage Best Practices

Source Secret Rotation

Replay Attack Prevention

1. Signature Verification

2. Deduplication

3. Timestamp Validation

4. IP Filtering

Multi-Tenant Security

Organization Isolation

Role-Based Access Control

Scoped API Keys

Field Encryption for PII

Securing Destination Endpoints

Authenticate Outbound Webhooks

HTTPS Only

Timeout Configuration

Production Security Checklist

Webhook Ingestion

API Access

Delivery

Monitoring

Team Access

Related Guides