Tracking Domain Registration with Webhooks

At DNSimple, offering a powerful API for domain management is at the core of what we do. DNSimple uses webhooks to deliver notifications via HTTP regarding changes or events in your account. With webhooks you can react to events like domain registrations, transfers, renewals, automatic renewals, zone changes, and a whole lot more. In an effort to continually make it easier to track registration state changes as they happen, today we're introducing a new webhook event: domain.state_change.

DNSimple now fires a domain.state_change webhook event whenever a domain transitions between hosted, registered, and expired registration states. Each event includes explicit from, to, and reason fields, so you can track lifecycle changes - like expirations, transfers out, or registration removals. This gives you a clearer way to follow domain state changes that existing events such as domain.register or domain.renew do not cover individually. This event helps you track registration lifecycle transitions for domains, especially transitions that were hard to observe from existing events alone.

Get every state transition of your domain without polling.

Customers and integrators often sync DNSimple domain data into external systems - billing platforms, monitoring dashboards, compliance databases. Existing events such as domain.register, domain.transfer, domain.renew, and domain.restore cover core flows, but they do not surface every lifecycle transition individually. For example, if a domain expires and you need to pause billing in your SaaS platform, or if a domain is transferred out and you need to clean up associated resources, there was no single event that told you the registration state changed. You would have to poll the API or infer the change from a combination of other signals.

domain.state_change solves this by giving you a direct domain expiration notification, domain transfer webhook, or registration event for every state transition - without polling.

What does the domain.state_change payload look like?

domain.state_change uses the standard DNSimple webhook envelope:

• name
• api_version
• request_identifier
• data
• account
• actor

The new addition is a state_change object with three fields:

• state_change.from: the registration state before the transition (hosted, registered, or expired)
• state_change.to: the registration state after the transition
• state_change.reason: string explaining the state change (registration, transfer_in, expiration, transfer_out, renewal, restoration, registration_removed)

State transitions and reasons

Each reason maps to a specific from/to transition:

Full payload example

{"data": {"domain": {"id": 181984, "name": "example-alpha.com", "state": "registered", "account_id": 1385, "auto_renew": false, "created_at": "2020-06-04T19:15:14Z", "expires_at": "2021-06-05T02:15:00Z", "expires_on": "2021-06-05", "updated_at": "2020-06-04T19:15:21Z", "unicode_name": "example-alpha.com", "private_whois": false, "registrant_id": 2715}, "state_change": {"from": "hosted", "to": "registered", "reason": "registration"}}, "name": "domain.state_change", "actor": {"id": "system", "entity": "dnsimple", "pretty": "support@dnsimple.com"}, "account": {"id": 1385, "display": "xxxxxxx-xxxxxxx-xxxxxxx", "identifier": "xxxxxxx-xxxxxxx-xxxxxxx@xxxxx.com"}, "api_version": "v2", "request_identifier": "a57e7761-3cfd-42a1-ba47-9ac89f5e69c3"}

For more information, see the Webhooks and Events documentation.

Getting started

Already using webhooks? No configuration change needed, simply add a handler for the domain.state_change event name to your existing webhook receiver. The event will be delivered automatically to all active webhook endpoints.

New to webhooks? Follow the Webhooks and API Events support guide to create your first endpoint, then handle domain.state_change alongside any other events you need.

Using the API? Visit our developer site Webhooks API reference and start implementing your own webhook handlers.

At DNSimple we have been working with webhooks for over a decade to make improvements that give you deeper visibility into your domain lifecycle. If you have any questions about webhooks, or anything else about DNSimple, get in touch - we're always here to help. Not using DNSimple yet? Give us a try, free for 30 days.

Share on Twitter and Facebook

Juan Ku

Backend engineer at the kernel.