Custom Domain Kit
Docs/Integration

Webhook Receiver

Webhook Receiver

Use webhooks to keep your SaaS database in sync after domain status changes.

Event Type

Custom Domain Kit sends:

domain.status_changed

The event is emitted when a domain reaches a terminal active or failed state.

Payload

{
  "id": "evt_123",
  "type": "domain.status_changed",
  "createdAt": "2026-06-30T12:00:00.000Z",
  "data": {
    "applicationId": "app_123",
    "domainId": "dom_123",
    "hostname": "docs.customer.com",
    "status": "active",
    "statusReason": null,
    "tenantId": "tenant_456",
    "actorId": "user_789"
  }
}

Delivery Headers

X-CustomDomainKit-Delivery: wdel_123
X-CustomDomainKit-Event: evt_123
X-CustomDomainKit-Timestamp: 1782216000
X-CustomDomainKit-Signature: v1=<hex-hmac>

Signature Verification

Verify the signature against:

timestamp + "." + raw_body

Use the webhook signing secret from the dashboard. Do not use the app secret.

Receiver Behavior

  • Reject requests with missing or invalid signatures.
  • Ignore duplicate event IDs.
  • Update the local domain row by domainId or hostname.
  • Return 2xx for events that were processed or safely ignored.
  • Log event ID, delivery ID, hostname, and status.