Production Readiness

Before launching your webhook pipeline to production, ensure your configuration follows security best practices and reliability standards. This guide provides a comprehensive checklist and detailed recommendations for running Hookbase securely and reliably.

Pre-Launch Checklist

Use this checklist to verify your production configuration:

Signature Verification

Signature verification is the most critical security control for webhooks. It ensures that incoming webhooks are authentic and haven't been tampered with.

Why It Matters

Without signature verification:

• Attackers can send fake webhooks to trigger unauthorized actions
• Replay attacks can resubmit legitimate webhooks
• Man-in-the-middle attacks can modify webhook payloads

Enabling Verification

When creating a source, always enable signature verification:

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/sources \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stripe Payments",
    "provider": "stripe",
    "verifySignatures": true,
    "rejectInvalidSignatures": true,
    "signingSecret": "whsec_abc123..."
  }'

Provider-Specific Configuration

Each provider has different signature verification mechanisms:

Reject vs. Accept Invalid Signatures

The rejectInvalidSignatures setting controls behavior when verification fails:

rejectInvalidSignatures: true (Recommended for Production)

• Invalid webhooks return 401 Unauthorized
• Event is NOT stored in Hookbase
• No deliveries are attempted
• Audit log records the rejection

rejectInvalidSignatures: false (Development/Testing Only)

• Invalid webhooks return 200 OK
• Event is stored with verificationStatus: "failed"
• Deliveries are still attempted (not recommended)
• Useful for debugging signature issues

Secret & Key Rotation

Regular rotation of secrets and API keys is essential for security hygiene.

API Key Rotation

Rotate API keys on a regular schedule (recommended: every 90 days):

Step 1: Create new API key

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/api-keys \
  -H "Authorization: Bearer CURRENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key (2026-Q2)",
    "scopes": ["read:sources", "read:events", "write:routes"],
    "expiresAt": "2026-06-01T00:00:00Z"
  }'

Step 2: Update services to use new key

• Deploy new key to all services that consume your webhooks
• Verify services are working with new key
• Monitor for authentication errors

Step 3: Revoke old key

curl -X DELETE https://api.hookbase.app/api/organizations/{orgId}/api-keys/{keyId} \
  -H "Authorization: Bearer NEW_API_KEY"

Source Signing Secret Rotation

For webhook sources, rotate signing secrets using the built-in rotation mechanism:

# Via CLI
hookbase sources rotate-secret 11111111-1111-4111-8111-111111111111 --org myorg
 
# Via API
curl -X POST https://api.hookbase.app/api/organizations/{orgId}/sources/{sourceId}/rotate-secret \
  -H "Authorization: Bearer YOUR_API_KEY"

This returns a new signingSecret. Update it in your webhook provider:

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "Stripe Payments",
  "signingSecret": "whsec_NEW_SECRET",
  "previousSecret": "whsec_OLD_SECRET",
  "secretRotatedAt": "2026-02-11T10:30:00Z"
}

Zero-Downtime Rotation Strategy

For critical production systems:

1. Pre-rotate: Create new secret but don't activate yet
2. Update provider: Configure webhook provider with new secret (but don't delete old config yet)
3. Activate: Rotate secret in Hookbase (both secrets now valid for 24h)
4. Monitor: Watch delivery success rates for any verification failures
5. Clean up: After 24h, remove old secret from provider configuration

Replay Prevention

Replay attacks involve resubmitting valid webhooks to trigger duplicate actions (e.g., double-charging a customer).

Deduplication

Enable deduplication to automatically reject duplicate webhooks:

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/sources \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Stripe Payments",
    "slug": "stripe-payments",
    "provider": "stripe",
    "dedupEnabled": true,
    "dedupStrategy": "auto",
    "dedupWindowHours": 24
  }'

Deduplication Strategies:

There is no field path to configure: the event ID is read from the place each provider puts it — Stripe's payload id, GitHub's X-GitHub-Delivery, Shopify's X-Shopify-Webhook-Id, and so on. To dedupe on a header of your own instead, name it in dedupCustomHeader.

dedupWindowHours accepts 1 to 168 (seven days).

Timestamp Checking

Many providers include a timestamp in their signature. Hookbase rejects webhooks whose timestamp falls outside that provider's tolerance window, which prevents replay of a captured request.

The tolerance is part of each provider's signature scheme, not a source setting — there is no timestampTolerance field to send. Stripe's is 300 seconds; a provider whose scheme does not sign a timestamp has no window to check. Selecting the right provider on the source is what turns this on.

Idempotency Keys in Destinations

For critical operations, ensure your destination endpoints support idempotency keys:

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/transforms \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Add Idempotency Header",
    "type": "jsonata",
    "expression": "{\"headers\": {\"Idempotency-Key\": $.event.id}}"
  }'

Attach this transform to routes delivering to payment processors or other systems where duplicate requests could cause problems.

Network Security

Control which traffic can reach your webhook sources and where deliveries can be sent.

IP Filtering

Restrict webhook sources to accept only traffic from known provider IPs:

curl -X PATCH https://api.hookbase.app/api/organizations/{orgId}/sources/{sourceId} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ipFilterMode": "allowlist",
    "ipAllowlist": [
      "3.18.12.0/22",
      "3.130.192.0/22"
    ]
  }'

ipFilterMode is one of none, allowlist, denylist, or both. Each entry is a bare IPv4 or IPv6 address or CIDR string — there is no per-entry description field, so keep the annotated list in your own infrastructure code. Setting both checks the denylist first.

Provider IP Ranges:

HTTPS-Only Enforcement

Never send webhooks to unencrypted HTTP endpoints. Use an https:// URL when you create the destination:

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/destinations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Processor",
    "slug": "payment-processor",
    "url": "https://api.example.com/webhooks"
  }'

Destination URLs are validated on create and update, but for SSRF rather than for encryption. A URL is rejected when it:

• uses a scheme other than http: or https:
• resolves to a private, loopback, link-local or otherwise internal host
• embeds credentials, as in https://user:pass@host/path
• uses a port outside 80, 443, 8080, 8443, 3000, 4000, 5000, 8000 and 9000

To confirm what a destination is really pointed at, read it back:

curl https://api.hookbase.app/api/destinations/{destinationId} \
  -H "Authorization: Bearer YOUR_API_KEY"

Custom Domains with SSL

For inbound webhooks, use custom domains with SSL certificates:

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/custom-domains \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "webhooks.example.com",
    "sslMode": "full_strict"
  }'

This allows webhooks at https://webhooks.example.com/receive/{sourceSlug} with your own SSL certificate, improving trust and branding.

Data Protection

Protect sensitive data in webhook payloads both at rest and in transit.

Field Encryption

Encrypt PII fields before storing or forwarding webhooks:

Field encryption is a property of the source, set with encryptFields on create or update. There is no separate endpoint and no per-field algorithm to pick — everything uses AES-256-GCM.

curl -X PATCH https://api.hookbase.app/api/organizations/{orgId}/sources/{sourceId} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "encryptFields": [
      "$.customer.email",
      "$.customer.ssn",
      "$.payment.cardNumber"
    ]
  }'

Encrypted fields are replaced in the stored payload with an ENC: prefix followed by the ciphertext:

{
  "customer": {
    "email": "ENC:qm9YbGF0ZWQtY2lwaGVydGV4dA==",
    "name": "John Doe"
  }
}

A field that is absent or null in a given payload is skipped rather than failing the event.

Field Masking

For non-encrypted fields that shouldn't appear in logs:

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/sources \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Events",
    "maskedFields": [
      "$.customer.email",
      "$.payment.last4",
      "$.customer.phone"
    ]
  }'

Masked fields appear as *** in audit logs and the dashboard but are delivered normally to destinations.

Payload Retention Policies

Retention is determined by your plan and is not configurable per organization. A scheduled retention job reads each organization's plan, works out a single cutoff date from that plan's retention window, and deletes everything older than it: events, their stored payloads in R2, delivery attempts, tunnel requests and cron execution history. Higher plans retain longer; a plan with unlimited retention is never cleaned up.

To see the window that applies to you, read your plan's limits:

curl https://api.hookbase.app/api/organizations/{orgId}/billing \
  -H "Authorization: Bearer YOUR_API_KEY"

Reliability Configuration

Configure retry policies, circuit breakers, and failover for production-grade reliability.

Retry Policies

Route deliveries use a fixed retry schedule. There is no per-destination retry configuration — a destination takes no retryPolicy, maxAttempts, or retryableStatusCodes, and sending them is silently ignored.

After the fifth attempt the delivery is marked failed and moves to the dead letter queue.

What is and is not retried:

• 5xx, 429, network errors, and timeouts are retried.
• Any other 4xx is a permanent failure — the delivery stops immediately with Permanent failure: HTTP <status> rather than using its remaining attempts. A destination that answers 401 while a token is being rotated will not be retried, so fix the credential and replay the delivery.

A destination's timeoutMs (1000-60000, default 30000) decides when an attempt counts as a timeout. That is the one delivery-timing knob a destination has.

Circuit Breaker Tuning

The circuit breaker is configured per route, not per destination — there is no /destinations/{id}/circuit-breaker endpoint. Three settings, all changed through one endpoint:

curl -X PATCH https://api.hookbase.app/api/organizations/{orgId}/routes/{routeId}/circuit-config \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "circuitFailureThreshold": 10,
    "circuitProbeSuccessThreshold": 3,
    "circuitCooldownSeconds": 60
  }'

Configuration Explained:

• circuitFailureThreshold: 10 (1-50) — open the circuit after 10 consecutive failures. There is no rolling window: one success resets the count
• circuitProbeSuccessThreshold: 3 (1-10) — close the circuit after 3 consecutive successful probes
• circuitCooldownSeconds: 60 (30-3600) — wait 60s in the open state before probing

There is no enable flag. The breaker is always active for a route on a plan that includes it, and circuitFailureThreshold: 50 is the way to make it effectively never trip.

For High-Traffic Routes:

{
  "circuitFailureThreshold": 50,
  "circuitProbeSuccessThreshold": 10,
  "circuitCooldownSeconds": 300
}

For Critical Low-Traffic Routes:

{
  "circuitFailureThreshold": 3,
  "circuitProbeSuccessThreshold": 1,
  "circuitCooldownSeconds": 30
}

Read the live state with GET /api/routes/{routeId}/circuit-status, and clear a stuck one with POST /api/routes/{routeId}/reset-circuit. See the Routes API.

Failover Setup

Failover is configured with two flat fields on the route. There is no failover object and no trigger list — the only trigger is the primary destination exhausting failoverAfterAttempts.

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/routes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Processing with Failover",
    "sourceId": "11111111-1111-4111-8111-111111111111",
    "destinationId": "22222222-2222-4222-8222-222222220028",
    "failoverDestinationIds": ["22222222-2222-4222-8222-22222222002a", "22222222-2222-4222-8222-222222220033"],
    "failoverAfterAttempts": 3
  }'

• failoverDestinationIds takes up to 3 backups, tried one at a time in order. It may not contain the primary destination or a duplicate.
• failoverAfterAttempts is 1-5 and must not exceed the 5 attempts a delivery gets.

Monitoring & Alerting

Set up proactive monitoring to catch issues before they impact customers.

Notification Channels

A channel is a destination for alerts. Creating one is two steps: create the channel, then link it to each route you want alerts about. The create body is validated strictly and accepts only name, type and config — any other key is a 400.

Slack — config.webhookUrl must begin with https://hooks.slack.com/:

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/notification-channels \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering Alerts",
    "type": "slack",
    "config": {
      "webhookUrl": "https://hooks.slack.com/services/T00/B00/xxx"
    }
  }'

Email — the key is emails, a non-empty array:

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/notification-channels \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "On-Call Email",
    "type": "email",
    "config": {
      "emails": ["oncall@example.com", "devops@example.com"]
    }
  }'

Webhook (for Datadog, a custom receiver, anything HTTP) — url, plus optional method (POST or PUT, default POST), headers and secret. A secret makes Hookbase sign the body and send it as X-Hookbase-Signature: sha256=…:

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/notification-channels \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Datadog Events",
    "type": "webhook",
    "config": {
      "url": "https://http-intake.logs.datadoghq.com/api/v2/logs",
      "headers": {
        "DD-API-KEY": "YOUR_DATADOG_API_KEY"
      },
      "secret": "a-shared-secret-for-hmac"
    }
  }'

The six types and the config each one requires:

Anything else in config is stored but never read.

Linking a Channel to a Route

A channel on its own alerts about nothing. The link both scopes the alerting and carries the triggers:

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/notification-channels/{channelId}/routes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routeId": "{routeId}",
    "notifyOnFailure": true,
    "notifyOnCircuitOpen": true,
    "notifyOnRecovery": true,
    "notifyOnSuccess": false
  }'

Returns {"success": true}. Linking the same route twice returns a 400 (Route is already linked to this channel); to change the triggers on an existing link, PATCH .../notification-channels/{channelId}/routes/{routeId} instead.

What to Alert On

There are exactly four triggers, all booleans on the route link:

Failure alerts fire on the crossing, not on every failure: the check is for the consecutive count landing exactly on failureThreshold, so a route that keeps failing past it alerts once, not repeatedly. Recovery is the mirror image — a success only alerts if the count had reached the threshold first, so a single blip that self-heals is silent on both sides.

Quota and signature-verification problems surface elsewhere: quota usage on GET /api/organizations/{orgId}/billing (which returns plan, limits and usage) and the dashboard, and rejected signatures in the event list with a failed ingest status. Cron failures are alerted separately, via notifyOnFailure and notifyEmails on the cron job itself.

CLI Monitoring Commands

Use the CLI for real-time monitoring:

# Stream live events
hookbase events follow --source 11111111-1111-4111-8111-111111111111
 
# Recent events for one source
hookbase events list --source 11111111-1111-4111-8111-111111111111 --limit 50
 
# View recent failures
hookbase deliveries list --status failed --limit 50
 
# Failures for one destination
hookbase deliveries list --destination 22222222-2222-4222-8222-222222220002 --status failed
 
# Send a test payload to a destination
hookbase destinations test 22222222-2222-4222-8222-222222220002
 
# Cron jobs status overview
hookbase cron status
 
# Watch cron executions as they run
hookbase cron follow --job cron_abc123

Health Endpoint Monitoring

Monitor Hookbase's health endpoint with external uptime services:

curl https://api.hookbase.app/health

Response:

{
  "status": "healthy",
  "timestamp": "2026-02-11T10:30:00Z",
  "services": {
    "database": "healthy",
    "queue": "healthy",
    "storage": "healthy"
  }
}

Use services like Pingdom, UptimeRobot, or Better Uptime to monitor this endpoint and alert on outages.

Access Control

Implement role-based access control and least privilege principles.

RBAC Overview

Hookbase supports three organization roles:

Assign a role when inviting a member — role defaults to member if omitted:

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/invites \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "engineer@example.com",
    "role": "member"
  }'

Changing an existing member's role is owner-only — an admin gets a 403 (Only owner can change roles):

curl -X PATCH https://api.hookbase.app/api/organizations/{orgId}/members/{userId} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "role": "admin" }'

API Key Scopes

API keys support fine-grained scopes for least privilege access:

Example: Read-Only Monitoring Key

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/api-keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Datadog Monitoring",
    "scopes": ["read:events", "read:deliveries"],
    "expiresAt": "2027-02-11T00:00:00Z"
  }'

Example: Route Management Key

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/api-keys \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dynamic Routing Service",
    "scopes": ["read:sources", "write:routes", "read:destinations"],
    "expiresAt": "2027-02-11T00:00:00Z"
  }'

Principle of Least Privilege

Grant the minimum scopes required:

{
  "name": "Frontend Dashboard",
  "scopes": ["admin"]
}

{
  "name": "Frontend Dashboard",
  "scopes": ["read:events", "read:deliveries", "read:sources"]
}

Audit Logging

All API key usage is logged in audit logs:

curl https://api.hookbase.app/api/organizations/{orgId}/audit-logs \
  -H "Authorization: Bearer YOUR_API_KEY"

Review audit logs for:

• Failed sign-ins (action: "user.login_failed")
• API key creation and revocation (action: "api_key.created", "api_key.revoked", "api_key.rotated")
• Source configuration changes (action: "source.updated")
• Member role changes (action: "member.role_changed")

Filter server-side with the action parameter rather than pulling everything:

curl "https://api.hookbase.app/api/organizations/{orgId}/audit-logs?action=user.login_failed&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

action, entityType and userId are the available filters; limit defaults to 50 and caps at 100, and offset pages through the rest.

Next Steps

• Custom Domains - Set up branded webhook URLs
• Audit Logs - Review security events
• Plans & Quotas - Understand plan limits
• Notification Channels - Configure alerts