An OpenSRS Domain Resellers Guide to Event Notifications : OpenSRS Test

Event Notifications let OpenSRS resellers receive alerts whenever the status of an asynchronous domain transaction changes — for example, order status updates, nameserver changes, renewals, or registrant changes. Instead of polling OpenSRS repeatedly, your system is told when something has happened. You can choose email notifications, API polling notifications, or both, and configure them per event type.

About event notifications

An asynchronous transaction is one where the registry processes the change in the background rather than completing it on the original API call. Event Notifications close that loop by signalling completion or status changes. See the Synchronous vs. Asynchronous Registries reference for the list of TLDs in each category.

Event notifications work for both Storefront domains and standard reseller domains.

Before you begin

You need access to the OpenSRS Reseller Control Panel.
Make sure the technical contact email address on your account is current — that is where email notifications will be delivered.
If you plan to use API polling, have your XML API client ready and able to call EVENT POLL and EVENT ACK.

Step 1: Configure notifications in the Reseller Control Panel

Sign in to the Reseller Control Panel.
Click Account Settings in the top right corner.
Select the Event Notifications tab.
Choose which events you want to be notified of and select email, API, or both for each event.

Tip: If you enable email, customize the email template under New Messaging → Event notification message (top right of the Control Panel) to control the destination address and message body.

Email notifications

When email is enabled, the OpenSRS system sends the technical contact on the account a message for every event. The body of the email is a JSON data structure intended to be parsed by a script or stored in a database.

Example: domain created

Subject: Event notification: DOMAIN: CREATED: 75675eb3d5010da7c8dbd1c638f7ca55

{"object_data":{"domain_name":"domainregistered.com","domain_id":"38391945","expiration_date":"2015-04-01T04:00:00Z"},"object":"DOMAIN","event_id":"75675eb3d5010da7c8dbd1c638f7ca55","event":"CREATED","event_date":"2014-09-09T21:16:22Z"}

Example: transfer status change

Subject: Event notification: TRANSFER: STATUS_CHANGE: 70ee0bd48660c737cc1b08501e214236

{"object_data":{"domain_name":"domainregistered.com","transfer_id":"8646809","order_id":0,"transfer_status":"completed"},"object":"TRANSFER","event_id":"70ee0bd48660c737cc1b08501e214236","event":"STATUS_CHANGE","event_date":"2014-09-09T21:16:23Z"}

Example: nameserver update

Subject: Event notification: DOMAIN: NAMESERVER_UPDATE: dc3295cdca977bbd227fda140ca7f4dc

{"object_data":{"domain_name":"domainregistered.com","domain_id":"38391945","nameserver_list":["ns1.systemdns.com","ns2.systemdns.com"]},"object":"DOMAIN","event_id":"dc3295cdca977bbd227fda140ca7f4dc","event":"NAMESERVER_UPDATE","event_date":"2014-09-09T21:17:48Z"}

API polling

When API polling is enabled, your client calls the OpenSRS XML API to retrieve queued events. After processing each event you must acknowledge it so it is removed from the queue.

Note: All dates are full ISO 8601 format (UTC). We recommend polling one event at a time, but you can set item key="limit" up to a maximum of 100 events per call.

Common fields

event — see the table below for each event type
event_id — unique identifier of this event
event_date — ISO 8601 UTC timestamp

Object-specific fields

DOMAIN object: domain_id, domain_name
ORDER object: order_id, domain_name
TRANSFER object: transfer_id, order_id, domain_name

Event types reference

Object	Event	Description	Additional fields
DOMAIN	CREATED	The domain was added to the system for any reason (registration, transfer completion, redemption, back-end import, etc.).	expiration_date
DOMAIN	EXPIRED	The domain has reached day 0 without being renewed.	expiration_date
DOMAIN	NAMESERVER_UPDATE	The nameservers set for this domain have changed.	nameserver_list — array of nameservers as set at the moment of the event
DOMAIN	REGISTERED	A domain registration has completed.	expiration_date, period (years registered)
DOMAIN	REGISTRANT_VERIFICATION_STATUS_CHANGE	The registrant verification status has changed.	verification_status — one of unverified, pending, verifying, marking_as_verified, verified, suspended, admin_reviewing, bounced, not_applicable
DOMAIN	RENEWED	Fires whenever a renewal is processed — auto-renewal or a manually created renewal order.	expiration_date, period (years renewed)
DOMAIN	ZONE_CHECK_STATUS_CHANGE	For .de and .fr, notifies when the DNS/zone check at the registry has passed or failed. Invalid status can cause the registry to disable the domain.	zone_check_status — valid or invalid
DOMAIN	DELETED	The domain was deleted.	reason — expired, transfered, auction, historical, by-request, delete-domain-api; deletion_date; redemption_grace_period_end_date
ORDER	CLAIM_STATUS_CHANGE	The claim status of an order has changed.	claim_status — initiated, declined, cancelled, accepted
ORDER	STATUS_CHANGE	The status of an order has changed.	order_status — cancelled, completed, declined, pending, pending_fax, processed, waiting; order_reg_type — landrush, new, premium, renewal, sunrise, transfer, whois_privacy
TRANSFER	STATUS_CHANGE	The status of a transfer has changed.	transfer_status — cancelled, completed, pending_admin, pending_owner, pending_registry

Warning: The status values, registrant verification states, and supported object types may have evolved since this article was last updated. Confirm against the current API reference at domains.opensrs.guide before relying on them.

Example API calls

Poll for events

Request:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">
<OPS_envelope>
  <header><version>0.9</version></header>
  <body>
    <data_block>
      <dt_assoc>
        <item key="protocol">XCP</item>
        <item key="object">EVENT</item>
        <item key="action">POLL</item>
        <item key="attributes">
          <dt_assoc>
            <item key="limit">1</item>
          </dt_assoc>
        </item>
      </dt_assoc>
    </data_block>
  </body>
</OPS_envelope>

Response:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">
<OPS_envelope>
  <header><version>0.9</version></header>
  <body>
    <data_block>
      <dt_assoc>
        <item key="protocol">XCP</item>
        <item key="object">EVENT</item>
        <item key="response_code">200</item>
        <item key="is_success">1</item>
        <item key="response_text">Command successful</item>
        <item key="action">REPLY</item>
        <item key="attributes">
          <dt_assoc>
            <item key="events">
              <dt_array>
                <item key="0">
                  <dt_assoc>
                    <item key="object_data">
                      <dt_assoc>
                        <item key="domain_name">abc-fictional.de</item>
                        <item key="domain_id">801743</item>
                        <item key="zone_check_status">invalid</item>
                      </dt_assoc>
                    </item>
                    <item key="object">DOMAIN</item>
                    <item key="event_id">6887c7d3838dcaec7517c531df527bb7</item>
                    <item key="event">ZONE_CHECK_STATUS_CHANGE</item>
                    <item key="event_date">2014-05-27T19:29:25Z</item>
                  </dt_assoc>
                </item>
              </dt_array>
            </item>
          </dt_assoc>
        </item>
      </dt_assoc>
    </data_block>
  </body>
</OPS_envelope>

Acknowledge an event

After receiving poll results, you must ACK each event to remove it from the notification queue. Unacknowledged events will keep being returned on subsequent polls.

Request:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">
<OPS_envelope>
  <header><version>0.9</version></header>
  <body>
    <data_block>
      <dt_assoc>
        <item key="protocol">XCP</item>
        <item key="object">EVENT</item>
        <item key="action">ACK</item>
        <item key="attributes">
          <dt_assoc>
            <item key="event_id">6887c7d3838dcaec7517c531df527bb7</item>
          </dt_assoc>
        </item>
      </dt_assoc>
    </data_block>
  </body>
</OPS_envelope>

Response:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<!DOCTYPE OPS_envelope SYSTEM "ops.dtd">
<OPS_envelope>
  <header><version>0.9</version></header>
  <body>
    <data_block>
      <dt_assoc>
        <item key="protocol">XCP</item>
        <item key="object">EVENT</item>
        <item key="response_code">200</item>
        <item key="is_success">1</item>
        <item key="response_text">Command successful</item>
        <item key="action">REPLY</item>
        <item key="attributes">
          <dt_assoc>
            <item key="events_remaining">0</item>
          </dt_assoc>
        </item>
      </dt_assoc>
    </data_block>
  </body>
</OPS_envelope>

Note: The original article also attached example responses for every event type.

Next steps

Decide on email vs. API polling. Use email for low-volume integrations and human review; use API polling for high-volume automated systems that need to process events programmatically.
Implement ACK handling. If you poll without acknowledging, the queue will keep replaying events — make ACK part of your event-processing loop.
Check TLD sync/async behavior. Confirm whether the TLDs you sell are synchronous or asynchronous so you know which events to expect.

Questions? Contact OpenSRS Support.

How helpful was this article?

Thanks for your feedback!

Do you still need help? If so please submit a request here.

OpenSRS Help Integration API & Developer Resources Event Notifications

Event Notifications