Search in this section

Skip to end of metadata
Go to start of metadata


Table of Contents

General

System notifications are asynchronous notifications that inform you of the status of an order. They are sent with a time delay because other instances, such as the registry, are involved in executing the process.

The system sends two types of asynchronous responses

  • Job notifications
  • Event notifications

Job Notifications

Job notifications are system responses related to an request sent to the system. For an incoming request, the system immediately sends a system response in real time with the status type notify, which reports the start of processing. After processing the job, the system sends an job notification with the final job status, which can be either success on successful processing or error on failed processing.

Event Notifications (Notify)

Event notifications are notifications that are triggered by external events, such as an outgoing transfer or owner validation. Event notifications are sent to the owner of the object.

Events that trigger an event notification

TransferOut
  • transfer_start
    Start of an outgoing domain transfer
  • transfer_autoack
    Automatic confirmation of an outgoing domain transfer (AutoAck). Only for gTLDs.
  • transfer_autonack
    Automatic refusal of an outgoing transfer (AutoNack).
  • transfer_reminder
    Reminder of an ongoing transfer.
  • domain_away
    Deletion of a domain from the database, e.g. in the case of domain transfers without the participation of the registrar.
DomainAutoUpdate
  • autoupdate_dns_error
    Successful execution of an automatic update. Only for .de domains. An automatic update is only performed if the connectivity check, which is part of the registration process, has failed.
  • autoupdate_dns_success
    Successful connectivity check
  • autoupdate_deffered_success

  • autoupdate_deffered_error

OCVAL (OwnerC validation)
  • ocval_reminder
    Reminder to deactivate the domain (5 days before).
  • ocval_activation
    Information about the disconnection of the name servers and the non-accessibility of the domain.
  • ocval_deactivation
    Information about the reconnection of the nameservers and the re-accessibility of the domain.

Receiving asynchronous System Notifications

You can retrieve asynchronous system responses using Polling or by Push or Email.

Configuration in the interface

The notifications can be configured in the AutoDNS interface (User Settings / User Profile / API Settings).

Configuration for Emails

For Email three different notification formats can be defined:

  • Standard: The email content consists of text and XML.
  • XML: The email content consists of pure XML.
  • JSON: The email content is pure JSON.

Configuration for Polling

Three different notification formats can be defined for Polling. The set format is used if the message is not retrieved and is sent by the system via email.

  • XML: The email content consists of pure XML.
  • JSON: The email content consists of pure JSON.
  • EPP: The email content consists of pure EPP (will be set automatically as soon as EPP API is activated).

Configuration for Push

Two different notification formats can be defined for Push. The set format is used if the message is not retrieved and is sent by the system via email.

    XML: The email content consists of pure XML.
    JSON: The email content consists of pure JSON.

Polling

Polling is the active retrieval of system notifications by the user. The notifications are available in structured format and are processed according to the FIFO principle.

Get Notifications

JSON: The current system notification can be retrieved via the GET /poll route.

XML: The current system notification can be retrieved via the task 0905.

Beispiel

Request
GET /poll



Response
{
    "stid": "20180926-stid",
    "status": {
        "code": "S0905",
        "text": "The notification was polled successfully.",
        "type": "SUCCESS"
    },
    "object": {
        "type": "message",
        "value": "1819917"
    },
    "data": [
        {
            "summary": 1,
            "message": {
                "id": 1819917,
                "job": {
                    "id": 4295609745,
                    "domain": {
                        "created": "2018-09-26T15:11:21.000+0200",
                        "owner": {},
                        "updater": {},
                        "name": "example.com",
                        "expire": "2019-09-26T15:11:20.000+0200",
                        "payable": "2019-09-26T15:11:21.000+0200",
                        "ownerc": {
                            "id": 100
                        },
                        "adminc": {
                            "id": 100
                        },
                        "techc": {
                            "id": 100
                        },
                        "registryStatus": "LOCK",
                        "nameServers": [
                            {
                                "name": "a.ns14.net"
                            },
                            {
                                "name": "b.ns14.net"
                            },
                            {
                                "name": "c.ns14.net"
                            },
                            {
                                "name": "d.ns14.net"
                            }
                        ],
                        "lastAction": "CREATE",
                        "authinfo": "gg9o3FFL/hzNbuPw",
                        "autoRenewStatus": "TRUE",
                        "registrarStatus": "ACTIVE",
                        "rddsOptIn": "NOT_SET"
                    }
                },
                "stid": "20180926-stid",
                "object": {
                    "type": "domain",
                    "value": "example.com"
                },
                "status": {
                    "code": "S0101",
                    "type": "SUCCESS"
                }
            }
        }
    ]
}
Request
<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <code>0905</code>
    </task>
</request>
Response
<response>
    <result>
        <data>
            <summary>1</summary>
            <message>
                <id>1855680</id>
                <owner>
                    <user>alex_normal_plus</user>
                    <context>4</context>
                </owner>
                <job>
                    <domain>
                        <name>example.com</name>
                        <expire>2019-10-15 14:02:40</expire>
                        <payable>2019-10-15 14:02:41</payable>
                        <ownerc>100</ownerc>
                        <adminc>100</adminc>
                        <techc>100</techc>
                        <nic_member_label>VGRS-TEST</nic_member_label>
                        <registry_status>LOCK</registry_status>
                        <nserver>
                            <name>a.ns14.net</name>
                        </nserver>
                        <nserver>
                            <name>b.ns14.net</name>
                        </nserver>
                        <nserver>
                            <name>c.ns14.net</name>
                        </nserver>
                        <nserver>
                            <name>d.ns14.net</name>
                        </nserver>
                        <period>1</period>
                        <authinfo>S0Lygv+ZkNbniICm</authinfo>
                        <autorenew>true</autorenew>
                        <confirm_order>1</confirm_order>
                        <confirm_owner_consent>0</confirm_owner_consent>
                        <registrar_status>ACTIVE</registrar_status>
                        <rdds_opt_in>NOT_SET</rdds_opt_in>
                        <owner/>
                        <updater/>
                        <created>2018-10-15 14:02:41</created>
                    </domain>
                    <job_id>4295625406</job_id>
                    <status>
                        <code>S0101</code>
                        <type>success</type>
                        <object>
                            <type>domain</type>
                            <value>example.com</value>
                        </object>
                    </status>
                    <stid>20181015-app1-3788</stid>
                </job>
                <created>2018-10-15 14:03:02</created>
            </message>
        </data>
        <status>
            <code>S0905</code>
            <text>The notification was polled successfully.</text>
            <type>success</type>
            <object>
                <type>message</type>
                <value>1855680</value>
            </object>
        </status>
    </result>
    <stid>20181015-app1-3805</stid>
</response>

Confirm Notifications

JSON: A specific system notification can be confirmed via the route PUT /poll/{id}. The ID can be taken from the notification.

XML: A specific system notification can be confirmed with the task 0906. The ID can be taken from the notification.

Hints concerning the successfull delivery of a push notification

Notifications are considered "successfully delivered" if they have been confirmed by the user.

If a notification is not confirmed by the user within 24 hours, it will be delivered to the fallback email (reply_to from the request).

Beispiel

Request
PUT /poll/{id}
Response
{
    "stid": "20180926-stid",
    "status": {
        "code": "S0906",
        "text": "The notification was confirmed successfully.",
        "type": "SUCCESS"
    },
    "object": {
        "type": "message",
        "value": "1819853"
    }
}
Request
<request>
    <auth>
        <user>USER</user>
        <context>CONTEXT</context>
        <password>PASSWORD</password>
    </auth>
    <task>
        <code>0906</code>
       <message>
            <id>650664</id>
        </message>
    </task>
</request>
Response
<response>
    <result>
        <data>
            <summary>0</summary>
            <message>
                <id>650664</id>
            </message>
        </data>
        <status>
            <code>S0906</code>
            <text>The notification was confirmed successfully.</text>
            <type>success</type>
            <object>
                <type>message</type>
                <value>650664</value>
            </object>
        </status>
         <stid>20181015-app1-3162</stid>
	 </result>
</response>

Push

Push is the passive retrieval of system notifications. The notifications are sent by the system to a specified address (URL) using HTTP.

Target addresses

HTTP and HTTPS addresses are possible. We recommend the use of HTTPS addresses.

Source IP of the push notification

The Source IP is 62.116.129.216.

Configure your firewall accordingly so that push notifications are not filtered out.

Hints concerning the successfull delivery of a push notification

Notifications are considered as "successfully delivered" if the server sends an HTTP Status 200 response.

If a URL is defined as forwarding, it will be resolved.

If a notification cannot be sent within 24 hours, it will be delivered to the fallback email address (reply_to from the request).


Example PHP script for writing the push message to a textfile

This script will process the PUSH Message and write it to output.txt.   Define this Script (URL+Script) In the User Profile under the API settings.

<?php
// Helper methods
function getHeaderList() {
        $headerList = array();
        foreach ($_SERVER as $name => $value) {
                if (preg_match('/^HTTP_/',$name)) {
                        $name = strtr(substr($name,5),'_',' ');
                        $name = ucwords(strtolower($name));
                        $name = strtr($name,' ','-');
                        // add to list
                        $headerList[$name] = $value;
                 }
        }
    return $headerList;
}

// Variables
$file = "output.txt";

// Fetch headers
$headers = "";
foreach (getHeaderList() as $name => $value) {
   $headers .= $name . ': ' . $value . "\n";
}

// Fetch body
$body = file_get_contents('php://input');

// Fetch current date
$now = date('Y-m-d H:m:s', time());

$content = "Date: $now\nHeaders: $headers\nBody: $body\n---------------------------------------------------------------------------------\n";

// Write to file
file_put_contents($file, $content, FILE_APPEND);
?>

Email

Notifications are sent by email (default setting).