Skip to content

Getting Started

Step 1: Expose an endpoint on your server

Notifications are sent as HTTP requests to an endpoint on your server. To receive notifications, you need: - A web server endpoint that it can make an HTTP(s) POST request to the provided webhook URL - The media type of the request will be set to application/json and is communicated in the Content-Type-header - The event is sent in the request body as a JSON string

Pattern of the webhook url, must use HTTPS protocol, can include ${eventId} which will be substituted by the id of the event when calling the webhook.

For basic authentication we recommend you to provide an API Key.

API Key examples

  • a9uj2ofd
  • doordonotthereisnotry
  • passonwhatyouhavelearned

Note: If the configured API key includes the prefix “Basic “, then the basic authentication scheme will be used and the API key will be sent in the HTTP header “Authorization”. Otherwise, the API key will be sent in the HTTP header “x-api-key” (typical for webhooks deployed on AWS infrastructure).

HTTP header example

If the API key is A9uj2ofd then x-api-key: A9uj2ofd HTTP header will be sent when calling the webhook, if the API key is Basic A9uj2ofd then Authorization: Basic A9uj2ofd HTTP header will be sent

Step 2: Set up webhook url and API Key in CR internal tooling

Send the webhook to connected-retail-support@zalando.fi and the team will configure OEA for you within 24 hours.

Step 3: Accept notifications

To ensure that your server is properly accepting notifications, we require you to acknowledge every notification of any type with an [200] response. If we don't receive this response within 10 seconds, for example because your server is down, all notifications to your endpoint will be queued and retried. For more information, refer here.

When your server receives a notification:

  1. Verify the API key is included in the notification. This is to confirm that the notification was sent by Connected Retail, and was not modified during transmission.
  2. Store the notification in your database.
  3. Acknowledge the notification with the following response: [200]
  4. Apply your business logic. Make sure that you acknowledge the notification before applying any business logic, because a breakage in your business logic could otherwise prevent important updates from reaching your system.

Step 4: Test and go live

After the setup is completed by the CR Team then you will start receiving the events almost instantaneously. Please review events for 2 days before applying any business logic, because a breakage in your business logic could otherwise prevent important updates from reaching your system.