Push Notifications

The Push Notifications feature allows you to be notified immediately whenever certain events happen on the real.de Onlineshop platform, e.g. when a customer buys something from you. When an event occurs on the real.de Onlineshop servers, an HTTP POST request is sent to a callback URL that you define when you subscribe to the event. This makes your integration with the real.de Onlineshop platform more immediate and more efficient, since you are notified right away when an event occurs, instead of having to periodically poll the API endpoints. Note that the notification does not contain the changed data, instead it just tells you that the data at a specific endpoint has changed. You will still need to do an API request to the specified endpoint to retrieve the new data.

Subscribing to Notifications for an Event

To subscribe to an event, you need to send an HTTP POST request to the /subscriptions/ endpoint. In the body, you must send a JSON object with the following properties:

Example:

POST https://www.real.de/api/v1/subscriptions/

Request body:

{
	"callback_url": "https://example.com/hm_notifications.php",
	"fallback_email": "webmaster@example.com",
	"event_name": "order_new"
}

Response body:

EMPTY

Response header:

Location: /subscriptions/37/

The response Location header contains the API endpoint URL of the new subscription.

Callback URL Verification

When you subscribe to a new event, or modify an existing subscription, the real.de Onlineshop server will immediately make an HTTP GET request to your callback URL, in order to verify that the callback server is configured correctly. A query string with the following parameters will be sent with the request:

When your server receives this request, it must respond with a response body that contains only the challenge value. This confirms that this server is configured to accept callbacks and is working correctly.

Example request:

GET https://example.com/hm_notifications.php?mode=subscribe&challenge=dd4aeae00158dc91de38585805ad7410d79b4237f4928e6e466934284f638430

Correct response body:

dd4aeae00158dc91de38585805ad7410d79b4237f4928e6e466934284f638430

Here is the source code for a PHP script that will correctly answer the verification request:

<?php

if ('GET' == $_SERVER['REQUEST_METHOD']) {
	if (isset($_GET['mode']) && 'subscribe' == $_GET['mode']) {
		echo $_GET['challenge'];
		exit;
	}
}

Note: All push notification requests, including the verification request, have a 15 second timeout, so your server must always respond within this time frame.

Notification Requests

Once you have subscribed to an event, the real.de Onlineshop servers will do an HTTP POST request to your callback URL whenever that event occurs. The request will contain the following headers:

The notification request will also contain a JSON object in the body, with the following fields:

Here is an example notification request:

POST https://example.com/hm_notifications.php

Request headers:

HM-Timestamp 1432815691
HM-Signature c57523ff08413a7eaf88447ba2405c0632fbefecff7b3426d94fd1c4b7482caa

Request body:

{
	"event_name": "order_new",
	"resource": "/orders/123456789/",
	"id_message": "393b6341da2bbeb7bdb27c579fe4b4eb",
	"payload": "[]"
}

Your callback server must return a 200 HTTP status code within 15 seconds. The body of the response can be empty and no response headers are required. If the notification request times out, or the response’s status code is anything other than 200, the system will assume that the notification was not processed, and will queue it to be retried later. See the Callback URL Unreachable section for details about notification retries.

In order to stay under the timeout limit, we recommend using a message broker or job queue like RabbitMQ, NSQ, Gearman, IronMQ or many others. This allows you to queue the event and respond to the notification request immediately. Then, a background worker can do the API request to get the current resource data and do whatever actions are needed to handle the event in your system.

Callback URL Unreachable

Your callback URL should always be available to receive notifications, 24/7. However, we understand that no one has perfect uptime, so if your server is down or a notification request times out, we will retry the notification at increasing intervals for about 12 hours. Each notification always includes an id_message in the body, which contains a unique ID for the event occurrence. Each retry of the notification will always contain the same id_message, so you can tell if two notifications are repeats of the same event, or if they are for two separate occurrences.

If your server comes back online within 12 hours, you will receive all notifications for all events that occurred while the server was down, but not immediately, and not necessarily in the order they occurred. Each time a notification request is unsuccessful, we queue it to be retried, but with an increasing interval between retries. For example, if the first notification attempt fails, we will retry the request after one minute. However, after several failures, we wait 15, 30 or 60 minutes between retries. This means that a notification that failed its first request one minute before your server comes back online will be delivered again right away, but other notifications could take up to one hour to arrive.

If your server is offline for more than 12 hours, we will disable your push notification subscription and send an email to the address specified as the fallback_email when you subscribed to the event. Once your server is ready to receive notifications again, you can re-enable the subscription with a PATCH request to the subscription’s API endpoint. However, events that occurred while your subscription was disabled are lost. You must query the corresponding API endpoint to get all resources that changed during the downtime.

Retrieving Current Subscriptions

You can retrieve your current event subscriptions by sending an HTTP GET request to the /subscriptions/seller/ endpoint. You can optionally specify the event_name query parameter to filter subscriptions by event name.

Example:

GET https://www.real.de/api/v1/subscriptions/seller/

Response body:

[
	{
		"id_subscription": 37,
		"callback_url": "https://example.com/hm_notifications.php",
		"fallback_email": "webmaster@example.com",
		"event_name": "order_new",
		"is_active": true
	}
]

Modifying a Subscription

To update a subscription you need to send an HTTP PATCH request to the /subscriptions/{id_subscription}/ endpoint and supply the same callback_url, fallback_email, and event_name information as in the subscription creation request. Additionally, you must supply an is_active flag to switch the subscription on or off.

Note: Every time you modify the callback URL it will be re-verified by the real.de Onlineshop servers. You can find more information about the verification process in the Callback URL Verification section.

Example:

PATCH https://www.real.de/api/v1/subscriptions/37/

Request body:

{
	"callback_url": "https://example.com/hm_notifications.php",
	"fallback_email": "webmaster@example.com",
	"event_name": "order_new",
	"is_active": false
}

Unsubscribing from an Event

To delete a subscription you need to send an HTTP DELETE request to the /subscriptions/{id_subscription}/ endpoint. The subscription will immediately be permanently deleted.

Example:

DELETE https://www.real.de/api/v1/subscriptions/37/

Events

Currently we only offer notifications for some events, but we will be adding more soon.