Event: `domain.status_changed`

Fires whenever a domain in your InboxKit account transitions to a new lifecycle status.

🔗 This page documents one of the four events delivered to your webhook URL. For the shared HTTP contract, headers, signature verification, and retry logic, see the Webhook Integration & Signature Verification page.

Applies to

Scope	Value
Providers	All — domains are provider-agnostic.
Trigger	Any significant change to `domain.status`.
Typical cadence	Delivered to your endpoint within approximately 30 seconds of the status change.

Headers (reminder)

POST /your-path HTTP/1.1
Content-Type: application/json
User-Agent: InboxKit-Webhook/1.0
X-InboxKit-Event: domain.status_changed
X-InboxKit-Timestamp: 2024-01-10T15:30:45.123Z
X-InboxKit-Signature: sha256=<hex>

Payload envelope

{
  "event": "domain.status_changed",
  "timestamp": "<ISO 8601 UTC>",
  "team_id": "<your team uid>",
  "team_name": "<your team name>",
  "data": {
    "domain": { /* see fields below */ },
    "metadata": { /* see fields below */ }
  }
}

`data.domain` fields

Every field InboxKit sends in a domain.status_changed webhook is listed below.

Field	Type	Nullable	Description
`uid`	string	no	Unique, stable identifier for this domain. Use this as your idempotency key.
`name`	string	no	Fully qualified domain name (e.g. `yourdomain.com`).
`tld`	string	no (may be empty)	Top-level domain, lowercased (e.g. `"com"`). Empty string if not set.
`status`	enum	no	New status. See the status reference table below.
`previous_status`	string \| null	yes	Previous status before this transition, if known.
`dns_propagation_status`	enum	no	`pending` \| `waiting` \| `propagated` \| `failed` \| `errored`.
`nameservers`	string[]	no	List of nameservers assigned to the domain. Empty array if none. For purchased domains this is typically InboxKit-managed; for connected domains it's whatever the customer set at their registrar.
`renewal_date`	ISO 8601 \| null	yes	When the domain is next due for renewal.
`renewal_status`	enum	no	`na` \| `pending` \| `completed` \| `failed`.
`registration_years`	integer	no	How many years the domain was registered for.
`registration_date`	ISO 8601 \| null	yes	When the domain was first registered with InboxKit.
`price`	number	no	Price paid in the team's billing currency. `0` if not applicable.
`connection_type`	enum	no	`purchased` \| `connected` \| `""` (empty when not yet set).
`forwarding_url`	string	no (may be empty)	URL-level forwarding target, if configured.
`forwarding_email`	string	no (may be empty)	Email-level forwarding target, if configured.
`forwarding_status`	enum	no (may be empty)	`""` \| `pending` \| `processing` \| `completed` \| `failed` \| `retrying`.
`enable_mask_forwarding`	boolean	no	Whether forwarding uses masking.
`dmarc_email`	string	no (may be empty)	DMARC report recipient.
`catch_all_email`	string	no (may be empty)	Catch-all mailbox address.
`assigned_mailboxes`	integer	no	Number of mailboxes currently using this domain.
`available_mailboxes`	integer	no	Remaining mailbox capacity on this domain.
`tags`	string[]	no	Free-form tags you've applied to the domain.

`data.metadata` fields

Field	Type	Description
`updated_at`	ISO 8601	When the domain document was last updated in InboxKit's database. Useful for ordering / deduping.
`workspace_id`	string	Internal workspace identifier the domain belongs to.

Status values that emit webhooks

The following domain status values do trigger a domain.status_changed webhook when a domain transitions to them:

Status	What it means
`cart`	Domain is in the shopping cart.
`registration_in_progress`	Registrar is processing the new domain registration.
`dns_setup_pending`	Domain is registered; DNS records still need to be applied.
`waiting_for_dns_propagation`	DNS records are published; waiting for global propagation.
`active`	Fully operational — DNS is propagated, domain is ready to host mailboxes.
`inactive`	Domain is configured but not currently serving traffic.
`payment_failed`	Payment (usually a renewal) failed; the customer needs to retry billing.
`cancelled`	Subscription cancelled.
`deleted`	Fully removed from InboxKit. Terminal state.

Status values that exist but do NOT emit webhooks

The following statuses exist in InboxKit but do not emit a webhook when a domain transitions to them. You will never receive an event for one of these transitions:

pending_payment, payment_processing, refunded, refunded_due_to_banned_keywords, not_connected, no_longer_available, scheduled_for_deletion, expired_propagation, pending_activation.

You may still see them as the previous_status of an event that transitions out of them (e.g. pending_payment → active fires because the new status is active).

Example receiver (Node.js)

Examples

Use the selector on the right-hand side to see different realistic transitions. All six examples below are transitions to statuses that actually emit webhooks in production.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location --request POST 'https://api.inboxkit.com/webhook' \ --header 'X-InboxKit-Signature: sha256=b0344c61d8db38e0f469e85fc6e8c055e0742e8d9a9c5a9e8e4d3f7c5a8b9c0d' \ --header 'X-InboxKit-Event: domain.status_changed' \ --header 'X-InboxKit-Timestamp: 2024-01-10T15:30:45.123Z' \ --header 'User-Agent: InboxKit-Webhook/1.0' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "event": "domain.status_changed", "timestamp": "2024-01-10T15:30:45.123Z", "team_id": "ABC-123-DEF-TEAM", "team_name": "Marketing Team", "data": { "domain": { "uid": "ABC-123-DEF-DOMAIN", "name": "yourdomain.com", "tld": "com", "status": "active", "previous_status": "pending_payment", "dns_propagation_status": "propagated", "nameservers": [ "ns1.inboxkit.com", "ns2.inboxkit.com" ], "renewal_date": "2025-01-10T00:00:00.000Z", "renewal_status": "na", "registration_years": 1, "registration_date": "2024-01-10T00:00:00.000Z", "price": 12.99, "connection_type": "purchased", "forwarding_url": "", "forwarding_email": "", "forwarding_status": "", "enable_mask_forwarding": false, "dmarc_email": "", "catch_all_email": "", "assigned_mailboxes": 0, "available_mailboxes": 50, "tags": [ "production", "primary" ] }, "metadata": { "updated_at": "2024-01-10T15:30:45.123Z", "workspace_id": "ABC-123-DEF-WORKSPACE" } } }'

Event: Domain Status Changed

Event: `domain.status_changed`

Applies to

Headers (reminder)

Payload envelope

`data.domain` fields

`data.metadata` fields

Status values that emit webhooks

Status values that exist but do NOT emit webhooks

Example receiver (Node.js)

Examples

Request

Responses

Event: Domain Status Changed

Event: domain.status_changed#

Applies to#

Headers (reminder)#

Payload envelope#

data.domain fields#

data.metadata fields#

Status values that emit webhooks#

Status values that exist but do NOT emit webhooks#

Example receiver (Node.js)#

Examples#

Request

Responses

Event: `domain.status_changed`

Applies to

Headers (reminder)

Payload envelope

`data.domain` fields

`data.metadata` fields

Status values that emit webhooks

Status values that exist but do NOT emit webhooks

Example receiver (Node.js)

Examples