Server Integration

Your server owns setup-session creation and webhook processing. The browser should never sign setup tokens.

Setup-session Endpoint

Recommended endpoint:

GET /api/custom-domain/setup-session?tenantId=tenant_456&actorId=user_789

Return:

{
  "apiBaseUrl": "https://cdk.example.com",
  "appId": "app_123",
  "tenantId": "tenant_456",
  "actorId": "user_789",
  "setupToken": "cdk_st_..."
}

Set:

Cache-Control: no-store

Permission Checks

Before returning a setup session, verify that:

• The user is signed in.
• The user can manage custom domains for tenantId.
• The tenant is allowed to use custom domains under your own plan rules.
• actorId represents the current operator or a trusted service actor.

Setup Token Payload

Sign a short-lived token with:

{
  "appId": "app_123",
  "tenantId": "tenant_456",
  "actorId": "user_789",
  "expiresAt": "2026-06-30T12:15:00.000Z",
  "nonce": "random-uuid"
}

Use a short TTL, such as 15 minutes.

Refresh Behavior

The embedded setup UI accepts setup-token-refresh-url. When a setup API request fails because the setup token expired, the component calls the refresh URL, updates the in-memory session, and retries once.

Webhook Endpoint

Your webhook receiver should:

1. Read the raw request body.
2. Verify the timestamp and X-CustomDomainKit-Signature.
3. Parse the JSON payload.
4. De-duplicate by event ID.
5. Update the local domain row.
6. Return 2xx when the event is processed or safely ignored.