Destinations

Destinations are where webhooks get delivered after processing. Hookbase supports two categories of destinations: HTTP endpoints for real-time delivery and warehouse destinations for batch ingestion into object storage.

Destination Types

HTTP Destinations

HTTP destinations deliver each webhook event to an endpoint in real time. This is the default destination type.

Creating an HTTP Destination

Required Fields

Optional Fields

What Headers a Delivery Carries

A delivery is a fresh HTTP request, not a forwarded copy of the one the provider sent. Hookbase builds its headers from scratch, in this order:

1. Content-Type — from the transform's output, or the event's own content type when no transform runs
2. User-Agent: Hookbase/1.0
3. X-Delivery-ID — this delivery attempt's id, stable across retries of the same delivery
4. X-Event-ID — the event id, shared by every delivery fanned out from one event
5. The destination's own headers object (below), which can override any of the above
6. The destination's auth header — Authorization for bearer/basic, or your chosen header name for api_key/custom_header
7. Any one-shot overrides from a replay-with-edit, applied last

No header the provider sent is included. X-GitHub-Event, Stripe-Signature, X-Shopify-Topic and every other inbound header stop at ingest — a handler that reads them off a Hookbase delivery gets nothing. Read what you need out of the body, or set it yourself on the destination.

Of the inbound headers, five are stored on the event and so remain visible in the dashboard, the events API and a payload export: content-type, user-agent, x-github-event, x-gitlab-event and stripe-signature. Everything else is dropped rather than stored, deliberately — it keeps secrets and arbitrary vendor headers out of the datastore.

Custom Headers

Add custom headers to every webhook delivery:

{
  "headers": {
    "Authorization": "Bearer your-api-key",
    "X-Custom-Header": "custom-value",
    "X-Source": "hookbase"
  }
}

Common use cases:

• Authentication tokens
• API keys
• Tracking headers
• Environment identifiers

Retry Schedule

Retries are not configurable per destination. Every route delivery gets the same five attempts:

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

A 5xx, a 429, a network error, or a timeout is retried. Any other 4xx is permanent — the delivery stops immediately rather than using its remaining attempts, so a destination answering 401 during a credential rotation needs the credential fixed and the delivery replayed.

The one delivery-timing field a destination has is timeoutMs, which decides when an attempt counts as a timeout.

Success Criteria

A delivery is considered successful when:

• HTTP status code is 2xx (200-299)
• Response is received within timeout (30 seconds)

Failure Handling

After all retries are exhausted:

• The delivery is marked as failed
• The event is moved to the dead letter queue
• You can manually replay from the dashboard

Example: Creating an HTTP Destination

curl -X POST https://api.hookbase.app/api/destinations \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API",
    "slug": "production-api",
    "type": "http",
    "url": "https://api.yourapp.com/webhooks/handler",
    "headers": {
      "Authorization": "Bearer sk_live_xxx",
      "X-Webhook-Source": "hookbase"
    },
    "timeoutMs": 15000
  }'

Warehouse Destinations

Warehouse destinations batch webhook events and upload them as structured files (JSONL or JSON) to object storage. This is useful for analytics, compliance archival, and batch processing pipelines.

How Batching Works

When events arrive, Hookbase queues them for batch delivery. The warehouse queue accumulates up to 100 events or waits 30 seconds (whichever comes first), then uploads a single file to your bucket.

Events for different destinations are grouped separately, so each destination receives its own files.

File Path Pattern

Files are stored using a predictable path structure:

{prefix}/{partition}/{timestamp}-{destination_id}.{format}

The partition segment depends on your configuration:

File Formats

Each row written to a warehouse destination is the webhook payload itself. Hookbase does not wrap it in an envelope — there is no event_id or received_at field in the file. If you need the event id alongside the data, project it in with a field mapping (below) or keep an HTTP destination in parallel.

JSONL (Recommended)

One JSON object per line. Works well with AWS Athena, BigQuery external tables, and streaming processors:

{"type":"payment_intent.succeeded","data":{"amount":2500}}
{"type":"customer.created","data":{"email":"user@example.com"}}

JSON Array

Set "fileFormat": "json" to get a single pretty-printed array containing the batch instead:

[
  {
    "type": "payment_intent.succeeded",
    "data": { "amount": 2500 }
  },
  {
    "type": "customer.created",
    "data": { "email": "user@example.com" }
  }
]

Amazon S3

{
  "type": "s3",
  "config": {
    "bucket": "my-data-lake",
    "region": "us-east-1",
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "prefix": "webhooks/stripe/",
    "fileFormat": "jsonl",
    "partitionBy": "date"
  }
}

Cloudflare R2

R2 destinations connect via R2's S3-compatible API using AWS4-HMAC-SHA256 signing. You'll need an R2 API token with read/write access to your bucket.

{
  "type": "r2",
  "config": {
    "bucket": "my-webhook-archive",
    "endpoint": "https://ACCOUNT_ID.r2.cloudflarestorage.com",
    "accessKeyId": "your-r2-access-key-id",
    "secretAccessKey": "your-r2-secret-access-key",
    "prefix": "webhooks/",
    "fileFormat": "jsonl",
    "partitionBy": "date"
  }
}

Google Cloud Storage

{
  "type": "gcs",
  "config": {
    "bucket": "my-gcs-bucket",
    "projectId": "my-gcp-project",
    "serviceAccountKey": "{\"type\":\"service_account\",\"project_id\":\"...\"}",
    "prefix": "webhooks/",
    "fileFormat": "jsonl",
    "partitionBy": "date"
  }
}

Azure Blob Storage

{
  "type": "azure_blob",
  "config": {
    "accountName": "myaccount",
    "accountKey": "base64-encoded-key",
    "containerName": "webhook-data",
    "prefix": "webhooks/",
    "fileFormat": "jsonl",
    "partitionBy": "date"
  }
}

Credential Security

Sensitive fields (secretAccessKey, serviceAccountKey, accountKey) are encrypted at rest using AES-256-GCM with organization-scoped keys. When you retrieve a destination via the API or dashboard, credentials are redacted and displayed as •••• followed by the last 4 characters.

When updating a destination, sending back the redacted value preserves the existing credential. You only need to provide a new value if you are rotating keys.

Field Mapping

By default each row is the raw webhook payload. Set a fieldMapping to write a flat, columnar schema instead — each row becomes a projection built only from the mappings you list:

{
  "fieldMapping": [
    { "source": "data.amount", "target": "amount", "type": "number" },
    { "source": "data.currency", "target": "currency", "type": "string" },
    { "source": "type", "target": "event_type", "type": "string" },
    { "source": "created", "target": "created_at", "type": "timestamp" }
  ]
}

timestamp runs the value through new Date(value).toISOString(); json stringifies anything that is not already a string. A mapping whose path is missing and which has no default is left out of the row entirely, so rows in the same file can have different keys.

With a field mapping set, the row contains only your mapped columns:

{"amount":2500,"currency":"usd","event_type":"payment_intent.succeeded","created_at":"2026-02-21T14:29:58.000Z"}

Testing a Warehouse Destination

Use the Test Connection action (in the dashboard or via API) to verify credentials and permissions. Hookbase uploads a small test file to your bucket and returns the file key, size, and event count.

curl -X POST https://api.hookbase.app/api/destinations/{destinationId}/test \
  -H "Authorization: Bearer whr_your_api_key"

{
  "success": true,
  "result": {
    "key": "hookbase/2026-02-21/test-1740150000000.jsonl",
    "size": 142,
    "count": 1
  }
}

Managing Destinations

List Destinations

curl https://api.hookbase.app/api/destinations \
  -H "Authorization: Bearer whr_your_api_key"

Get Destination Details

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

Update Destination

curl -X PATCH https://api.hookbase.app/api/destinations/{destinationId} \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourapp.com/webhooks/v2/handler"
  }'

Delete Destination

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

Destination Health

Monitor destination health in the dashboard:

• Success Rate: Percentage of successful deliveries
• Average Latency: Mean response time
• Last Delivery: Timestamp of most recent delivery
• Status: Active, degraded, or failing

Best Practices

1. Use HTTPS: Always use HTTPS URLs for HTTP destinations

2. Set appropriate timeouts: Ensure your endpoint responds within 30 seconds

3. Return 2xx quickly: Acknowledge receipt quickly, process asynchronously if needed

4. Handle duplicates: Webhooks may be delivered more than once; implement idempotency

5. Monitor health: Set up alerts for destinations with high failure rates

6. Use staging destinations: Test changes with a staging destination before production

7. Choose the right partition strategy: Use date for low-volume sources, hour for high-volume sources, and source when you need to query by origin

8. Use JSONL for analytics: JSONL is better suited for data lake queries than JSON arrays

Troubleshooting

Destination shows high failure rate

1. Check if the destination URL is accessible
2. Verify authentication headers are correct
3. Check your application logs for errors
4. Use the Event Debugger to inspect request/response

Webhooks not being delivered

1. Verify the destination is enabled
2. Check if routes are configured correctly
3. Ensure filters aren't blocking events
4. Check the dead letter queue for failed deliveries

Warehouse test connection fails

1. Verify bucket/container name is correct
2. Check that credentials have write permissions
3. For S3, ensure the region matches the bucket's actual region
4. For GCS, verify the service account key JSON is valid
5. For Azure, confirm the account key is base64-encoded

See Also

• Destinations API — Full API reference
• Routes — Connect sources to destinations
• Failover Destinations — Configure backup endpoints
• Circuit Breaker — Automatic protection for unhealthy destinations