Push Notifications

The Push Notifications feature allows you to be notified immediately whenever certain events happen on the Kaufland marketplace, e.g. when a customer buys something from you. When an event occurs on the Kaufland marketplace 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 Kaufland marketplace 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. As a query parameter you should provide the storefront for which you want to receive push notifications - for example ?storefront=de (see the Storefront section for more details and currently-supported storefronts). In the body, you must send a JSON object with the following properties:

  • callback_url - A publicly-accessible URL that will receive a POST request for each event notification with a maximum length of 255 characters.
  • fallback_email - An email address that will receive an email if we can’t reach the callback URL for an extended period of time and we disable your subscription.
  • event_name - The name of the event you are subscribing to. See the Events section for all currently-supported events.

Example:

POST https://sellerapi.kaufland.com/v2/subscriptions?storefront=de

Request body: 

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

Response body: 

{
   "data": {
     "id_subscription": 11011,
     "callback_url": "https://example.com/hm_notifications.php",
     "fallback_email": "test@kaufland.de",
     "event_name": "order_new",
     "is_active": true,
     "storefront": "de"
   }
}

Callback URL Verification

When you subscribe to a new event, or modify an existing subscription, the Kaufland marketplace 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:

  • mode - The string "subscribe".
  • challenge - A random string.

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 Kaufland marketplace servers will do an HTTP POST request to your callback URL whenever that event occurs. The request will contain the following headers:

  • Shop-Timestamp - The unix timestamp of the time when the event occurred.
  • Shop-Signature - A MAC signature for the request. This signature is generated using your key_secret, with the same function that you use to sign your API requests. This is a security feature which allows you to verify that the request is really coming from the Kaufland marketplace, since only you and the Kaufland marketplace have your key_secret. The signature generation function is described on the Rest API page. When you receive a notification, you should generate a signature for the request and verify that it is the same as the one specified in the Shop-Signature header.

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

  • event_name - The name of the event. This is the same as the event_name you specified when you subscribed to the event.
  • id_message - A unique ID for the event occurrence. If the request is a retry because of a problem with the callback server, this ID will be the same as one in a previous request, otherwise it will be globally unique. See the Callback URL Unreachable section for more information about notification retries.
  • resource - The URL of the resource that changed.
  • storefront - The storefront where event happened.
  • payload For certain events we provide all relevant data for the event in the field payload. For events that do not support the feature the field will remain empty.

Here is an example notification request:

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

Request headers: 

Shop-Timestamp 1432815691
Shop-Signature c57523ff08413a7eaf88447ba2405c0632fbefecff7b3426d94fd1c4b7482caa

Request body: 

{
	"event_name": "order_new",
	"resource": "/orders/123456789/",
	"id_message": "393b6341da2bbeb7bdb27c579fe4b4eb",
	"storefront": "de",
	"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/ endpoint. You can optionally specify the event_name and storefront query parameters to filter subscriptions by event name or storefront.

Example:

GET https://sellerapi.kaufland.com/v2/subscriptions

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
		"storefront": "de"
	}
]

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, event_name and storefront 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 Kaufland.de Onlineshop servers. You can find more information about the verification process in the Callback URL Verification section.

Example:

PATCH https://sellerapi.kaufland.com/v2/subscriptions/37/

Request body: 

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

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://sellerapi.kaufland.com/v2/subscriptions/37/

Events

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

  • order_new - This event is triggered once each time a customer places an order which includes one or more of your products. If a customer buys 5 products from you in a single order, only 1 order_new event notification will be sent.
  • order_unit_new - This event is triggered each time one of your units is ordered. If a customer buys 5 products from you in a single order, 5 separate order_unit_new notifications will be sent.
  • order_unit_status_changed - This event is triggered each time when the status of one of your units has been changed.
  • item_changed - This event is triggered each time when a product has changed.
  • category_changed - This event is triggered each time a category has changed.
  • return_new - This event is triggered each time a customer starts a return process.
  • return_status_changed - This event is triggered each time when the status of a customer return has been changed.
  • return_unit_status_changed - This event is triggered each time when the status of a customer return unit has been changed.
  • item_unit_new - This event is triggered each time when a new unit for a given Product has been created. Information about the unit will be sent in the field payload.
  • item_unit_changed - This event is triggered each time when one of the adjustable properties of a unit has been changed. Information about the unit will be sent in the field payload.
  • item_unit_deleted - This event is triggered each time when a has been deleted and cannot be sold anymore. Information about the unit will be sent in the field payload.
  • item_unit_out_of_stock - This event is triggered each time when a unit is out of stock (amount = 0). Information about the unit will be sent in the field payload.
  • item_unit_not_available - This event is triggered each time when a unit is set from available to onhold, which prevents it from being sold until it is set to available again. Information about the unit will be sent in the field payload.
  • item_unit_available - This event is triggered each time when a unit is set from onhold to available, so it can be sold again. Information about the unit will be sent in the field payload.

Storefront

You are able to get push-notifications on different callback urls based on the storefronts even for the same event. If you subscribed to de - german storefront, you will get notifications about events that have happened only for this storefront. You need to create notifications individually per storefront if you want to be notified for events happening on all of them.

Currently we support the following storefronts:

  • de - german storefront.
  • cz - czech storefront.
  • sk - slovakian storefront.