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

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

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"

Related

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

See Also

• Custom Domains API — Full API reference
• Sources — Configure webhook sources
• Enterprise Security — Security overview