Custom Domains

Custom domains let you use your own domain for webhook ingestion URLs instead of the default api.hookbase.app domain. This provides a branded experience and makes it easier to manage webhook URLs.

Domain Types

Type	Default URL	Custom URL
Source	https://api.hookbase.app/ingest/myorg/github	https://webhooks.yourapp.com/ingest/myorg/github
Tunnel	https://api.hookbase.app/t/abc-xyz-123	https://tunnel.yourapp.com/t/abc-xyz-123

Setup

Step 1: Create Domain

curl -X POST https://api.hookbase.app/api/custom-domains \
  -H "Authorization: Bearer whr_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "webhooks.yourapp.com",
    "type": "source"
  }'

Response:

{
  "id": "dom_abc123",
  "domain": "webhooks.yourapp.com",
  "type": "source",
  "status": "pending_verification",
  "verificationRecord": {
    "type": "CNAME",
    "name": "_hookbase-verify.webhooks.yourapp.com",
    "value": "verify.hookbase.app"
  },
  "cnameRecord": {
    "type": "CNAME",
    "name": "webhooks.yourapp.com",
    "value": "custom.hookbase.app"
  }
}

Step 2: Add DNS Records

Add both DNS records to your domain provider:

Verification record (temporary — can be removed after verification):

_hookbase-verify.webhooks.yourapp.com  CNAME  verify.hookbase.app

CNAME record (permanent):

webhooks.yourapp.com  CNAME  custom.hookbase.app

Step 3: Verify Domain

After DNS propagation (usually 1-15 minutes):

curl -X POST https://api.hookbase.app/api/custom-domains/dom_abc123/verify \
  -H "Authorization: Bearer whr_your_api_key"

Response:

{
  "id": "dom_abc123",
  "domain": "webhooks.yourapp.com",
  "status": "active",
  "sslStatus": "active",
  "verifiedAt": "2024-01-15T10:30:00Z"
}

SSL certificates are automatically provisioned and renewed via Cloudflare.

Domain Statuses

Status	Description
pending_verification	DNS records not yet verified
active	Domain verified and working
ssl_pending	Domain verified, SSL certificate being provisioned
failed	Verification failed — check DNS records

Troubleshooting

Verification Fails

1. Check DNS propagation — Use dig _hookbase-verify.webhooks.yourapp.com CNAME to verify the record exists
2. Wait for propagation — DNS changes can take up to 48 hours in some cases
3. Check for conflicts — Ensure no A record exists for the same hostname
4. Retry verification — Call the verify endpoint again after fixing DNS

SSL Issues

SSL certificates are provisioned automatically. If sslStatus remains pending:

1. Ensure the CNAME record points to custom.hookbase.app
2. Check that no CAA records on your domain block Cloudflare's CA
3. Wait up to 15 minutes for certificate issuance

Managing Domains

List Domains

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

Delete Domain

curl -X DELETE https://api.hookbase.app/api/custom-domains/dom_abc123 \
  -H "Authorization: Bearer whr_your_api_key"

WARNING

Deleting a custom domain reverts all webhook URLs to the default api.hookbase.app domain. Update your webhook providers accordingly.

Related

• Custom Domains API — Full API reference
• Sources — Webhook ingestion configuration
• Tunnels — Local development tunnels