Brand & White-Labeling

About 496 wordsAbout 2 min

GetHook supports white-labeling for SaaS products that embed webhook infrastructure under their own brand. Configure your company identity and register custom domains for branded ingest URLs.

Brand Settings

Brand settings apply to the entire account. Fields are optional — only set what you need.

Upsert brand settings

Creates or updates brand settings (last-write-wins per field).

POST /v1/brand-settings

Authentication: Bearer

Request body

All fields are optional.

Field	Type	Description
`company_name`	string	Your company name (e.g. `"Acme Corp"`)
`logo_url`	string	Public URL to your logo image
`primary_color`	string	Hex color code (e.g. `"#6366f1"`)
`docs_title`	string	Title shown in your branded docs (e.g. `"Acme Webhooks"`)
`support_email`	string	Support contact email

Response `200 OK`

{
  "data": {
    "id": "br1br2br3-...",
    "account_id": "a1a2a3a4-...",
    "company_name": "Acme Corp",
    "logo_url": "https://acme.example.com/logo.png",
    "primary_color": "#6366f1",
    "docs_title": "Acme Webhooks",
    "support_email": "support@acme.example.com",
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
}

curl examples

# Set all brand fields
curl -s -X POST http://localhost:8080/v1/brand-settings \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Corp",
    "logo_url": "https://acme.example.com/logo.png",
    "primary_color": "#6366f1",
    "docs_title": "Acme Webhooks",
    "support_email": "support@acme.example.com"
  }' | jq .

# Update only the logo
curl -s -X POST http://localhost:8080/v1/brand-settings \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"logo_url": "https://acme.example.com/new-logo.png"}' | jq .

Get brand settings

GET /v1/brand-settings

Authentication: Bearer

Response `200 OK`

Returns the current brand settings object, or {} if not configured.

curl example

curl -s http://localhost:8080/v1/brand-settings \
  -H "Authorization: Bearer $API_KEY" | jq .

Custom Domains

Create custom domain

POST /v1/custom-domains

Authentication: Bearer

Request body

Field	Type	Required	Description
`domain`	string	Yes	The domain to register (e.g. `"hooks.acme.example.com"`)
`type`	string	No	Domain purpose. One of: `"webhook"` (default)

Response `201 Created`

{
  "data": {
    "id": "cd1cd2cd3-...",
    "account_id": "a1a2a3a4-...",
    "domain": "hooks.acme.example.com",
    "type": "webhook",
    "status": "pending",
    "tls_status": "pending",
    "verification_token": "gethook-verify-a1b2c3d4e5f6",
    "created_at": "2024-01-15T10:00:00Z"
  }
}

Domain verification

After registering, add a DNS TXT record to verify ownership:

_gethook-verify.hooks.acme.example.com  TXT  "gethook-verify-a1b2c3d4e5f6"

DNS propagation typically takes 5–60 minutes. GetHook will check the record and update status to active automatically.

Errors

Status	Error	Cause
`400`	`domain is required`	Missing domain field
`401`	Unauthorized	Invalid Bearer token

curl example

curl -s -X POST http://localhost:8080/v1/custom-domains \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "hooks.acme.example.com",
    "type": "webhook"
  }' | jq .

List custom domains

GET /v1/custom-domains

Authentication: Bearer

Response `200 OK`

{
  "data": [
    {
      "id": "cd1cd2cd3-...",
      "account_id": "a1a2a3a4-...",
      "domain": "hooks.acme.example.com",
      "type": "webhook",
      "status": "pending",
      "tls_status": "pending",
      "verification_token": "gethook-verify-a1b2c3d4e5f6",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ]
}

Domain statuses

Field	Status	Meaning
`status`	`pending`	Awaiting DNS verification
`status`	`active`	DNS verified, domain is live
`status`	`failed`	Verification failed
`tls_status`	`pending`	TLS certificate provisioning in progress
`tls_status`	`active`	TLS certificate provisioned
`tls_status`	`failed`	TLS provisioning failed

curl example

curl -s http://localhost:8080/v1/custom-domains \
  -H "Authorization: Bearer $API_KEY" | jq .