DNS Events

DNS events are triggered when DNS records are added, updated, or deleted — and when domain forwarding changes.

Overview

Subscribe to dns-record.updated to get notified of any DNS change on a domain under your account. A single event type covers all actions: adds, updates, deletes, and forwarding changes — differentiated by the action field in the payload.

dns-record.updated

Fires whenever a DNS record is added, updated, or deleted, or when domain forwarding is configured.

When it occurs

A DNS record is added via POST /dns

A DNS record is updated via PUT /dns

A DNS record is deleted via DELETE /dns

Domain forwarding is set or changed

Example Payload — Record Added

{
  "event": "dns-record.updated",
  "data": {
    "action": "added",
    "domainName": "acmecorp.com",
    "userId": "H8M9JV2S9HMPYFQW393AZHQVD4XM",
    "record": {
      "id": "rec_7F2KP9QX",
      "host": "@",
      "recordType": "MX",
      "value": "mail.acmecorp.com"
    }
  }
}

Example Payload — Record Updated

{
  "event": "dns-record.updated",
  "data": {
    "action": "updated",
    "domainName": "acmecorp.com",
    "userId": "H8M9JV2S9HMPYFQW393AZHQVD4XM",
    "record": {
      "id": "rec_7F2KP9QX",
      "host": "mail",
      "recordType": "CNAME",
      "value": "ghs.googlehosted.com"
    }
  }
}

Example Payload — Record Deleted

{
  "event": "dns-record.updated",
  "data": {
    "action": "deleted",
    "domainName": "acmecorp.com",
    "userId": "H8M9JV2S9HMPYFQW393AZHQVD4XM",
    "record": {
      "id": "rec_7F2KP9QX",
      "host": "@",
      "recordType": "TXT",
      "value": "v=spf1 include:_spf.google.com ~all"
    }
  }
}

Example Payload — Forwarding Changed

{
    "event": "dns-record.updated",
    "data": {
      "action": "added",
      "domainName": "example.com",
      "userId": "usr_abc123",
      "record": {
        "host": "@",
        "recordType": "A",
        "value": "34.120.45.67",
        "forwardTo": "https://mysite.com",
        "maskForwarding": false
      }
    }
  }

Payload Schema

Field	Type	Description
`event`	string	Always `"dns-record.updated"`
`data.action`	string	`"added"`, `"updated"`, or `"deleted"`
`data.domainName`	string	The domain the record belongs to
`data.userId`	string	CMR userId of the user who owns the domain
`data.record.id`	string	Provider record ID
`data.record.host`	string\|null	Record host/subdomain (e.g. `@`, `mail`, `*`)
`data.record.recordType`	string\|null	Record type: `A`, `CNAME`, `MX`, `TXT`, `SRV`, etc.
`data.record.value`	string\|null	Record value

Notes

Deleted records: host, recordType, and value reflect the state before deletion. These will be null if the DNS provider was unreachable at the time of deletion — the delete still goes through.

Forwarding changes: fire with action: "added". The record fields may be null as forwarding is not a standard DNS record type.

All actions share one event name — filter by data.action to handle each case in your webhook handler.

Next Steps

Domain Events

Domain registration and renewal events.

DNS Management

API reference for adding and updating DNS records.

Mailbox Events

Mailbox provisioning and update events.

Overview#

dns-record.updated#

When it occurs#

Example Payload — Record Added#

Example Payload — Record Updated#

Example Payload — Record Deleted#

Example Payload — Forwarding Changed#

Payload Schema#

Notes#

Next Steps#