Troubleshooting

This guide helps you diagnose and resolve common webhook issues in Hookbase. Use it to debug delivery failures, signature verification errors, and event processing problems.

Common Issues

Webhooks Not Arriving

If your source is not receiving webhooks:

Check Source Status

Verify the source is Active in the dashboard
Inactive sources reject all incoming webhooks

Verify Ingestion URL

Ensure the provider is sending to https://api.hookbase.app/ingest/{orgSlug}/{sourceSlug}
Check that both orgSlug and sourceSlug match your organization and source exactly (case-sensitive)
Test the URL manually with curl:

bash

curl -X POST https://api.hookbase.app/ingest/{orgSlug}/{sourceSlug} \
  -H "Content-Type: application/json" \
  -d '{"test": "event"}'

Review IP Filtering

If IP filtering is enabled on the source, verify the provider's IPs are whitelisted
Check the source configuration:

bash

hookbase sources get src_xxx

Check Rate Limits

Free plan: 1,000 events/month, 10 requests/second
Starter plan: 10,000 events/month, 50 requests/second
Exceeded rate limits return HTTP 429 responses

Review Event Quota

Check your current usage in the dashboard under Settings → Billing
Events exceeding your plan quota are rejected

TIP

Enable Request Logging on your source to see all incoming requests, even those that fail validation.

Signature Verification Failures

If webhooks are rejected due to invalid signatures:

Wrong Secret

Verify you're using the correct signing secret from your provider
Update the source configuration:

bash

hookbase sources update src_xxx --secret "whsec_new_secret"

Wrong Algorithm

Ensure the verification algorithm matches your provider:
- Stripe uses HMAC-SHA256 with timestamp
- GitHub uses HMAC-SHA256
- Shopify uses HMAC-SHA256 (Base64)
- Twilio uses HMAC-SHA1
- Slack uses HMAC-SHA256

Clock Skew

Some providers include timestamps in signatures and reject requests older than 5 minutes
Verify your server time is synchronized with NTP
Check the X-Signature-Timestamp header (if present) against current time

Encoding Issues

Some providers send signatures in hex, others in Base64
Verify the encoding matches your provider's documentation
Hookbase auto-detects encoding for built-in integrations

Bypass for Testing

Temporarily disable signature verification:

bash

hookbase sources update src_xxx --no-verify

WARNING

Only disable signature verification in development. Always enable it in production to prevent spoofed webhooks.

Delivery Failures

If events are received but deliveries fail:

Destination URL Unreachable

Verify the destination URL is publicly accessible
Test manually:

bash

curl -X POST https://your-destination.com/webhook \
  -H "Content-Type: application/json" \
  -d '{"test": "delivery"}'

Timeouts

Default timeout: 30 seconds
If your endpoint takes longer, increase the timeout:

bash

hookbase destinations update dst_xxx --timeout 60

HTTP Error Codes

4xx errors (Client Error): No retries. Check payload format and authentication
5xx errors (Server Error): Automatic retries with exponential backoff
Review delivery response in dashboard or via API:

bash

curl https://api.hookbase.app/api/organizations/{orgId}/deliveries/dlv_xxx \
  -H "Authorization: Bearer YOUR_TOKEN"

SSL Certificate Issues

Ensure destination uses valid SSL certificate
Self-signed certificates are rejected by default
Use verifySSL: false for development only:

bash

hookbase destinations update dst_xxx --no-verify-ssl

Retry Behavior

Failed deliveries retry up to 5 times with exponential backoff: 1s, 2s, 4s, 8s, 16s
After 5 failures, delivery status becomes failed
Manually replay failed deliveries:

bash

hookbase deliveries replay dlv_xxx

Events Not Being Delivered

If events arrive but don't trigger deliveries:

Route Disabled

Check route status:

bash

hookbase routes get rte_xxx

Enable the route:

bash

hookbase routes update rte_xxx --enabled

Filter Blocking Events

Filters evaluate before delivery queuing
Test a filter against an event payload:

bash

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/filters/flt_xxx/test \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d @event-payload.json

Review filter logic in dashboard or update:

bash

hookbase filters update flt_xxx --condition "payload.type = 'order.created'"

Circuit Breaker Open

If a destination has 10+ consecutive failures, the circuit breaker opens
Check circuit breaker state:

bash

curl https://api.hookbase.app/api/organizations/{orgId}/destinations/dst_xxx/circuit-breaker \
  -H "Authorization: Bearer YOUR_TOKEN"

Reset the circuit breaker:

bash

hookbase destinations reset-circuit dst_xxx

Destination Inactive

Verify destination status:

bash

hookbase destinations get dst_xxx

Activate destination:

bash

hookbase destinations update dst_xxx --active

TIP

Use the Event Trace view in the dashboard to see why an event didn't match any routes.

Duplicate Deliveries

If the same event is delivered multiple times:

Retries After Timeout

If your endpoint takes longer than the timeout to respond, Hookbase retries
Solution: Respond with 2xx immediately, then process asynchronously
Increase timeout if needed:

bash

hookbase destinations update dst_xxx --timeout 60

Deduplication Not Enabled

Enable deduplication on the source using provider's ID field:

bash

hookbase sources update src_xxx \
  --dedup-enabled \
  --dedup-key "id" \
  --dedup-window 86400

Idempotency Key Handling

Use idempotency keys in your endpoint to handle duplicate deliveries
Hookbase includes X-Hookbase-Delivery-Id header in all requests
Store delivery IDs to detect duplicates

High Latency

If webhook delivery is slow:

Queue Backlog

Check queue depth in dashboard under Monitoring
Upgrade plan for higher throughput
Consider batching deliveries if destination supports it

Large Payloads

Payloads >1MB take longer to process
Use transforms to strip unnecessary fields:

jsonata

{
  "event": event,
  "type": type,
  "data": data.{
    "id": id,
    "status": status
  }
}

Slow Destination

Monitor destination response times in dashboard
Optimize your endpoint or increase timeout
Use async processing with immediate 200 OK response

Transform Complexity

Complex JSONata transforms add processing time
Test transform performance:

bash

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/transforms/tfm_xxx/test \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d @event-payload.json

Simplify transform logic where possible

Error Code Reference

Ingest Errors

HTTP status codes returned when webhooks are sent to your ingestion URL:

Code	Error	Cause	Solution
400	Bad Request	Invalid JSON or missing required fields	Check payload format
401	Unauthorized	Invalid signature	Verify signing secret and algorithm
403	Forbidden	IP not whitelisted	Add provider IP to source IP filter
404	Not Found	Invalid orgSlug or sourceSlug	Verify ingestion URL
413	Payload Too Large	Payload exceeds 10MB limit	Reduce payload size or contact support
429	Too Many Requests	Rate limit exceeded	Slow down request rate or upgrade plan

Delivery Errors

Status values on delivery records:

Status	Meaning	Cause	Solution
`timeout`	Destination didn't respond within timeout	Slow endpoint or network issue	Increase timeout or optimize endpoint
`connection_refused`	Destination refused connection	URL unreachable or port closed	Verify destination URL and firewall
`dns_error`	DNS lookup failed	Invalid domain name	Check destination hostname
`ssl_error`	SSL certificate invalid	Self-signed or expired cert	Use valid SSL cert or disable verification (dev only)
`http_4xx`	Client error (400-499)	Bad request format or auth	Check payload and authentication
`http_5xx`	Server error (500-599)	Destination server error	Fix destination endpoint or wait for recovery
`transform_error`	Transform failed	Invalid JSONata expression	Test and fix transform
`schema_failed`	Schema validation failed	Payload doesn't match schema	Update payload or schema

API Errors

Status codes from Hookbase API:

Code	Error	Cause	Solution
401	Unauthorized	Missing or invalid token	Authenticate with valid API key or JWT
403	Forbidden	Insufficient permissions	Check organization role (admin/editor/viewer)
404	Not Found	Resource doesn't exist	Verify resource ID and organization
409	Conflict	Resource already exists	Use different name or slug
422	Validation Error	Invalid request body	Check request against API documentation
429	Rate Limited	Too many API requests	Implement exponential backoff

Debugging Workflows

Tracing an Event End-to-End

Follow an event through the entire pipeline:

1. Find the Event

By event ID:

bash

hookbase events get evt_xxx

Or by query:

bash

hookbase events list --source src_xxx --status processed --limit 10

Via API:

bash

curl https://api.hookbase.app/api/organizations/{orgId}/events/evt_xxx \
  -H "Authorization: Bearer YOUR_TOKEN"

2. Check Deliveries

List deliveries for the event:

bash

curl https://api.hookbase.app/api/organizations/{orgId}/events/evt_xxx/deliveries \
  -H "Authorization: Bearer YOUR_TOKEN"

Or via CLI:

bash

hookbase deliveries list --event evt_xxx

3. Inspect Delivery Details

Get full delivery record:

bash

hookbase deliveries get dlv_xxx

View response body:

bash

curl https://api.hookbase.app/api/organizations/{orgId}/deliveries/dlv_xxx/response \
  -H "Authorization: Bearer YOUR_TOKEN"

4. Replay if Needed

Retry a failed delivery:

bash

hookbase deliveries replay dlv_xxx

TIP

Use the dashboard's Event Inspector to see the visual trace with routes, filters, transforms, and delivery attempts.

Checking Circuit Breaker State

View circuit breaker status for a destination:

bash

curl https://api.hookbase.app/api/organizations/{orgId}/destinations/dst_xxx/circuit-breaker \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

json

{
  "state": "open",
  "failureCount": 12,
  "lastFailureAt": "2026-02-11T10:30:00Z",
  "nextRetryAt": "2026-02-11T10:35:00Z"
}

Reset the circuit breaker:

bash

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/destinations/dst_xxx/circuit-breaker/reset \
  -H "Authorization: Bearer YOUR_TOKEN"

Or via CLI:

bash

hookbase destinations reset-circuit dst_xxx

Verifying Filter Configuration

Test a filter against sample payload:

bash

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/filters/flt_xxx/test \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "order.created",
    "amount": 5000,
    "currency": "USD"
  }'

Response:

json

{
  "matches": true,
  "evaluation": {
    "condition": "payload.amount > 1000",
    "result": true
  }
}

Update filter if needed:

bash

hookbase filters update flt_xxx \
  --condition "payload.amount > 1000 and payload.currency = 'USD'"

Checking Transform Output

Test a transform before applying:

bash

curl -X POST https://api.hookbase.app/api/organizations/{orgId}/transforms/tfm_xxx/test \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "order.created",
    "order": {
      "id": "ord_123",
      "items": [{"sku": "ABC", "quantity": 2}]
    }
  }'

Response:

json

{
  "output": {
    "event": "order.created",
    "orderId": "ord_123",
    "itemCount": 2
  },
  "executionTime": 12
}

Update transform:

bash

hookbase transforms update tfm_xxx \
  --expression '{
    "event": type,
    "orderId": order.id,
    "itemCount": $count(order.items)
  }'

CLI Debugging

Quick commands for debugging common issues:

List Failed Events

bash

hookbase events list --status failed --limit 20

Get Delivery Details

bash

hookbase deliveries get dlv_xxx

Replay Failed Delivery

bash

hookbase deliveries replay dlv_xxx

Follow Events in Real-Time

bash

hookbase events follow

Enable Debug Logging

bash

HOOKBASE_DEBUG=1 hookbase events follow

Check Recent Deliveries

bash

hookbase deliveries list --status failed --since 1h

Test Route Matching

bash

hookbase routes test rte_xxx --payload @event.json

View Audit Logs

bash

hookbase audit-logs list --action "delivery.failed" --limit 50

TIP

Set HOOKBASE_DEBUG=1 environment variable to see detailed HTTP requests and responses from the CLI.

Getting Help

If you're still experiencing issues:

Dashboard

Visit app.hookbase.app to view real-time event traces and delivery logs

API Documentation

Review the API Reference for endpoint specifications and examples

Support

Email: [email protected]
Live chat: Available in dashboard (Pro and Business plans)
Status page: status.hookbase.app

Community

Discord: discord.gg/hookbase
GitHub Issues: github.com/hookbase/hookbase/issues

When contacting support, include:

Event ID or Delivery ID
Organization ID and Source/Destination slugs
Timestamp of the issue
Error messages or HTTP status codes
Steps to reproduce

Troubleshooting ​

Common Issues ​

Webhooks Not Arriving ​

Signature Verification Failures ​

Delivery Failures ​

Events Not Being Delivered ​

Duplicate Deliveries ​

High Latency ​

Error Code Reference ​

Ingest Errors ​

Delivery Errors ​

API Errors ​

Debugging Workflows ​

Tracing an Event End-to-End ​

Checking Circuit Breaker State ​

Verifying Filter Configuration ​

Checking Transform Output ​

CLI Debugging ​

Getting Help ​

Troubleshooting

Common Issues

Webhooks Not Arriving

Signature Verification Failures

Delivery Failures

Events Not Being Delivered

Duplicate Deliveries

High Latency

Error Code Reference

Ingest Errors

Delivery Errors

API Errors

Debugging Workflows

Tracing an Event End-to-End

Checking Circuit Breaker State

Verifying Filter Configuration

Checking Transform Output

CLI Debugging

Getting Help