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",
    "domainType": "source",
    "targetId": "11111111-1111-4111-8111-111111111111"
  }'

Response:

{
  "id": "ffffffff-ffff-4fff-8fff-ffffffffffff",
  "domain": "webhooks.yourapp.com",
  "domainType": "source",
  "targetId": "11111111-1111-4111-8111-111111111111",
  "verificationStatus": "pending",
  "cnameTarget": "api.hookbase.app",
  "cfHostname": {
    "id": "0d89c70e-7b8a-4b1f-9f4c-0a1b2c3d4e5f",
    "status": "pending"
  }
}

Step 2: Add the DNS Record

One record, pointing at the value the response returned in cnameTarget:

webhooks.yourapp.com  CNAME  api.hookbase.app

That single CNAME does both jobs — Cloudflare uses it to prove you control the hostname and to route traffic once it resolves. There is no separate verification record to add or remove.

Step 3: Verify Domain

After DNS propagation (usually 1-15 minutes):

curl -X POST https://api.hookbase.app/api/custom-domains/ffffffff-ffff-4fff-8fff-ffffffffffff/verify \
  -H "Authorization: Bearer whr_your_api_key"

Response:

{
  "id": "ffffffff-ffff-4fff-8fff-ffffffffffff",
  "domain": "webhooks.yourapp.com",
  "verificationStatus": "verified",
  "cfHostnameStatus": "active",
  "cfSslStatus": "active",
  "justVerified": true,
  "validationErrors": [],
  "sslValidationErrors": []
}

A domain that has not passed yet is not an error: the same 200 comes back with verificationStatus still pending, and the reasons in validationErrors or sslValidationErrors. Call the endpoint again after DNS propagates.

SSL certificates are automatically provisioned and renewed via Cloudflare.

Verification Statuses

cfHostnameStatus and cfSslStatus carry Cloudflare's own states, which is where to look when verificationStatus is pending and you want to know which half is waiting.

Troubleshooting

Verification Fails

1. Check DNS propagation — Use dig webhooks.yourapp.com CNAME to confirm the record resolves to api.hookbase.app
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 cfSslStatus remains pending:

1. Ensure the CNAME record points to api.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/ffffffff-ffff-4fff-8fff-ffffffffffff \
  -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