Custom Domains API

Manage custom domains for webhook ingestion and tunnel endpoints.

Endpoints

Method	Path	Description
GET	/api/custom-domains	List custom domains
POST	/api/custom-domains	Create custom domain
GET	/api/custom-domains/{id}	Get custom domain
DELETE	/api/custom-domains/{id}	Delete custom domain
POST	/api/custom-domains/{id}/verify	Verify domain DNS

Custom Domain Object

{
  "id": "dom_abc123",
  "domain": "webhooks.yourapp.com",
  "type": "source",
  "status": "active",
  "sslStatus": "active",
  "verificationRecord": {
    "type": "CNAME",
    "name": "_hookbase-verify.webhooks.yourapp.com",
    "value": "verify.hookbase.app"
  },
  "cnameRecord": {
    "type": "CNAME",
    "name": "webhooks.yourapp.com",
    "value": "custom.hookbase.app"
  },
  "verifiedAt": "2024-01-15T10:30:00Z",
  "createdAt": "2024-01-01T00:00:00Z"
}

Domain Types

Type	Description
source	Custom domain for webhook ingestion URLs
tunnel	Custom domain for tunnel endpoints

Domain Statuses

Status	Description
pending_verification	DNS records not yet verified
active	Domain verified and serving traffic
ssl_pending	Verified, SSL certificate being provisioned
failed	Verification failed

List Custom Domains

GET /api/custom-domains

Example

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

Response

{
  "data": [
    {
      "id": "dom_abc123",
      "domain": "webhooks.yourapp.com",
      "type": "source",
      "status": "active",
      "sslStatus": "active"
    }
  ]
}

Create Custom Domain

POST /api/custom-domains

Request Body

Field	Type	Required	Description
domain	string	Yes	Fully qualified domain name
type	string	Yes	Domain type: source or tunnel

Example

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_new123",
  "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"
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

Add both DNS records to your domain provider before verifying.

Get Custom Domain

GET /api/custom-domains/{id}

Returns the full custom domain object.

Verify Domain

POST /api/custom-domains/{id}/verify

Checks DNS records and activates the domain if verification passes.

Example

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

Success Response

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

Failure Response

{
  "id": "dom_abc123",
  "domain": "webhooks.yourapp.com",
  "status": "failed",
  "error": "CNAME record not found. Expected: webhooks.yourapp.com → custom.hookbase.app"
}

Delete Custom Domain

DELETE /api/custom-domains/{id}

WARNING

Deleting a custom domain reverts all URLs to the default api.hookbase.app domain.

Example

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

Response

204 No Content

Error Responses

400 Bad Request

Invalid domain:

{
  "error": "Bad Request",
  "message": "Domain must be a valid fully qualified domain name",
  "code": "INVALID_DOMAIN"
}

409 Conflict

Domain already in use:

{
  "error": "Conflict",
  "message": "Domain 'webhooks.yourapp.com' is already registered",
  "code": "DOMAIN_IN_USE"
}

Related

• Custom Domains Guide — Setup walkthrough and troubleshooting