Event Notifications

Event Notifications allow resellers to receive notifications if the status of asynchronous domain transaction changes. Notification events include order status changes, nameserver updates, renewals, or registrant changes.  Please see our reference guide for details on which TLDs are Synchronous or Asynchronous.

While in the past resellers had to go back to OpenSRS and actively check the system if the status of an order had changed, OpenSRS will now actively tell them when something has changed. Through the Control Panel, they can configure which events they wish to be notified of, and if they prefer email or API notifications.

Event notifications work for storefront domains as well as normal domains.

To activate Event Notifications, please visit the Reseller Control Panel. Navigate to Account Settings page in the top right hand corner and select the Event Notifications tab to configure which events you would like to receive.

Which brings up the Account Settings page with the Event Notification tab :

If you enable the email option, you can configure where the email is sent and details included by navigating to New Messaging (top right hand corner of Control Panel) -> Event notification message template.

Email Notifications

Once emailed and triggered by an Event, the OpenSRS system sends the technical contact on the account an email for every Event.  The body of the email that is sent is a JSON data structure, intended for scripts or a database to parse.  Here are example Event Notification emails of a domain being transferred into the system, and having it's nameservers updated :

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"}

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"}

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"}

Here is a breakdown of the various items in the Event Notification email.

API Calls

Usage

When API polling for Event Notifications is enabled, you can send queries for events that have occurred.  The command syntax is below, followed by API examples.

Command Syntax

NOTE:
    - All dates are full ISO8601 format (UTC)

COMMON DATA

    event - (description for each below)
    event_id - unique identifier of this event
    event_date

COMMON DATA FOR OBJECT (within object_data): DOMAIN

    domain_id
    domain_name

COMMON DATA FOR OBJECT (within object_data): ORDER

    order_id
    domain_name

COMMON DATA FOR OBJECT (within object_data): TRANSFER

    transfer_id
    order_id
    domain_name

OBJECT: DOMAIN
EVENT: CREATED
DESCRIPTION: The domain was added to the system due to any number of actions including, registration, transfer completion, redemption, back-end import, etc.  Basically if a domain is added to our database for ANY reason, this event will be dispatched.

    expiration_date
   
OBJECT: DOMAIN
EVENT: EXPIRED
DESCRIPTION: The domain has reached DAY 0 without being renewed.

    expiration_date
   
OBJECT: DOMAIN
EVENT: NAMESERVER_UPDATE
DESCRIPTION: The nameservers set for this domain have changed.

    nameserver_list - Array of nameservers as set at the moment of this event

OBJECT: DOMAIN
EVENT: REGISTERED
DESCRIPTION: A domain registration has completed.

    expiration_date
    period - Number of years registered for
   
OBJECT: DOMAIN
EVENT: REGISTRANT_VERIFICATION_STATUS_CHANGE
DESCRIPTION: Notifies of a change to the registrant verification status for this domain.  This gives visibility into the state of a registrant's verification.  
    
    verification_status - unverified pending verifying marking_as_verified verified suspended admin_reviewing bounced not_applicable
    
OBJECT: DOMAIN
EVENT: RENEWED
DESCRIPTION: This event will be fired whenever a renewal is processed for a domain, whther it be through auto-renewal, or a manually created renewal order.
    
    expiration_date
    period - Number of years renewed for

OBJECT: DOMAIN
EVENT: ZONE_CHECK_STATUS_CHANGE
DESCRIPTION: For .de and .fr, will notify when the DNS/ZONE check has passed, or failed at the registry, as the domain is in jeopardy of being disabled by the registry if it remains invalid.

    zone_check_status - valid invalid

OBJECT: DOMAIN
EVENT: DELETED
DESCRIPTION:
    
    reason - expired transfered auction historical by-request delete-domain-api
    deletion_date
    redemption_grace_period_end_date

OBJECT: ORDER
EVENT: CLAIM_STATUS_CHANGE
DESCRIPTION:

    claim_status - initiated declined cancelled accepted

OBJECT: ORDER
EVENT: STATUS_CHANGE
DESCRIPTION:

    order_status - cancelled completed declined pending pending_fax processed waiting
    order_reg_type - landrush new premium renewal sunrise transfer whois_privacy

OBJECT: TRANSFER
EVENT: STATUS_CHANGE
DESCRIPTION:
    
    transfer_status - cancelled completed pending_admin pending_owner pending_registry

Example API Calls 

The Event Notifications use the standard OpenSRS API, with new commands available to poll for notifications. 

To begin, poll the OpenSRS server for Event Notification results. We recommend you query one event at a time, however you can set the item key="limit” to a maximum of 100 events per call.

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="transaction_id">2014-05-29 11:14:02 23004 101</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>
      <item key="total">1</item>
     </dt_assoc>
    </item>
   </dt_assoc>
  </data_block>
 </body>
</OPS_envelope>

Once you have received the poll results, you must ACK the event(s) to remove them from the Notification queue or they will keep being sent to you when you query 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">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="transaction_id">2014-05-29 11:17:03 22962 101</item>
    <item key="action">REPLY</item>
    <item key="attributes">
     <dt_assoc>
      <item key="total">0</item>
     </dt_assoc>
    </item>
   </dt_assoc>
  </data_block>
 </body>
</OPS_envelope>

Attached below are example responses for every type of Event Notification.